Webhook events

Every event shares one envelope. Subscribe with ["*"] or list the types you need. See Webhooks for signatures and retries.

Event	Status	When
message.received	Beta	A contact sent you a message
message.sent	Beta	A message was sent from Waasl (by an agent, workflow, AI agent or the API)
message.status_updated	Beta	Delivery status changed — sent, delivered, read or failed
conversation.created	Coming soon	A new conversation started
conversation.assigned	Coming soon	A conversation was assigned or unassigned
conversation.closed	Beta	A conversation was closed
conversation.stage_changed	Coming soon	A conversation moved to another lifecycle stage
contact.created	Coming soon	A contact was created
contact.updated	Coming soon	A contact’s details, tags or stage changed
template.status_updated	Beta	Meta approved, rejected, paused or disabled a template
channel.status_updated	Coming soon	A channel connected, disconnected, or its quality rating changed
broadcast.completed	Coming soon	A broadcast finished sending

message.received

Beta A contact sent you a message.

{
  "id": "evt_2Nq8Ld",
  "type": "message.received",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "message": {
      "id": "msg_Vb3kQ9xP",
      "conversation_id": "string",
      "direction": "in",
      "kind": "text",
      "body": "string",
      "caption": "string",
      "media_id": "string",
      "filename": "string",
      "mime": "string",
      "size_bytes": 0,
      "reply_to_id": "string",
      "actor_kind": "contact",
      "actor_id": "string",
      "status": "queued",
      "error": "Re-engagement message (131047)",
      "created_at": "2026-10-01T08:15:00Z"
    },
    "conversation": {
      "id": "cv_3PzA91",
      "contact_id": "string",
      "channel_id": "string",
      "channel_type": "whatsapp",
      "status": "open",
      "stage_id": "string",
      "assignee_id": "string",
      "team_id": "string",
      "controller": "human",
      "unread_count": 0,
      "tags": [
        "string"
      ],
      "last_customer_at": "2026-10-01T08:15:00Z",
      "last_message_at": "2026-10-01T08:15:00Z",
      "window_expires_at": "2026-10-01T08:15:00Z",
      "contact_name": "string",
      "contact_handle": "string"
    }
  }
}

message.sent

Beta A message was sent from Waasl (by an agent, workflow, AI agent or the API).

{
  "id": "evt_2Nq8Ld",
  "type": "message.sent",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "message": {
      "id": "msg_Vb3kQ9xP",
      "conversation_id": "string",
      "direction": "in",
      "kind": "text",
      "body": "string",
      "caption": "string",
      "media_id": "string",
      "filename": "string",
      "mime": "string",
      "size_bytes": 0,
      "reply_to_id": "string",
      "actor_kind": "contact",
      "actor_id": "string",
      "status": "queued",
      "error": "Re-engagement message (131047)",
      "created_at": "2026-10-01T08:15:00Z"
    },
    "conversation": {
      "id": "cv_3PzA91",
      "contact_id": "string",
      "channel_id": "string",
      "channel_type": "whatsapp",
      "status": "open",
      "stage_id": "string",
      "assignee_id": "string",
      "team_id": "string",
      "controller": "human",
      "unread_count": 0,
      "tags": [
        "string"
      ],
      "last_customer_at": "2026-10-01T08:15:00Z",
      "last_message_at": "2026-10-01T08:15:00Z",
      "window_expires_at": "2026-10-01T08:15:00Z",
      "contact_name": "string",
      "contact_handle": "string"
    }
  }
}

message.status_updated

Beta Delivery status changed — sent, delivered, read or failed.

{
  "id": "evt_2Nq8Ld",
  "type": "message.status_updated",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "message": {
      "id": "msg_Vb3kQ9xP",
      "conversation_id": "string",
      "direction": "in",
      "kind": "text",
      "body": "string",
      "caption": "string",
      "media_id": "string",
      "filename": "string",
      "mime": "string",
      "size_bytes": 0,
      "reply_to_id": "string",
      "actor_kind": "contact",
      "actor_id": "string",
      "status": "queued",
      "error": "Re-engagement message (131047)",
      "created_at": "2026-10-01T08:15:00Z"
    },
    "conversation": {
      "id": "cv_3PzA91",
      "contact_id": "string",
      "channel_id": "string",
      "channel_type": "whatsapp",
      "status": "open",
      "stage_id": "string",
      "assignee_id": "string",
      "team_id": "string",
      "controller": "human",
      "unread_count": 0,
      "tags": [
        "string"
      ],
      "last_customer_at": "2026-10-01T08:15:00Z",
      "last_message_at": "2026-10-01T08:15:00Z",
      "window_expires_at": "2026-10-01T08:15:00Z",
      "contact_name": "string",
      "contact_handle": "string"
    }
  }
}

conversation.created

Coming soon A new conversation started.

{
  "id": "evt_2Nq8Ld",
  "type": "conversation.created",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "conversation": {
      "id": "cv_3PzA91",
      "contact_id": "string",
      "channel_id": "string",
      "channel_type": "whatsapp",
      "status": "open",
      "stage_id": "string",
      "assignee_id": "string",
      "team_id": "string",
      "controller": "human",
      "unread_count": 0,
      "tags": [
        "string"
      ],
      "last_customer_at": "2026-10-01T08:15:00Z",
      "last_message_at": "2026-10-01T08:15:00Z",
      "window_expires_at": "2026-10-01T08:15:00Z",
      "contact_name": "string",
      "contact_handle": "string"
    }
  }
}

conversation.assigned

Coming soon A conversation was assigned or unassigned.

{
  "id": "evt_2Nq8Ld",
  "type": "conversation.assigned",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "conversation": {
      "id": "cv_3PzA91",
      "contact_id": "string",
      "channel_id": "string",
      "channel_type": "whatsapp",
      "status": "open",
      "stage_id": "string",
      "assignee_id": "string",
      "team_id": "string",
      "controller": "human",
      "unread_count": 0,
      "tags": [
        "string"
      ],
      "last_customer_at": "2026-10-01T08:15:00Z",
      "last_message_at": "2026-10-01T08:15:00Z",
      "window_expires_at": "2026-10-01T08:15:00Z",
      "contact_name": "string",
      "contact_handle": "string"
    }
  }
}

conversation.closed

Beta A conversation was closed.

{
  "id": "evt_2Nq8Ld",
  "type": "conversation.closed",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "conversation": {
      "id": "cv_3PzA91",
      "contact_id": "string",
      "channel_id": "string",
      "channel_type": "whatsapp",
      "status": "open",
      "stage_id": "string",
      "assignee_id": "string",
      "team_id": "string",
      "controller": "human",
      "unread_count": 0,
      "tags": [
        "string"
      ],
      "last_customer_at": "2026-10-01T08:15:00Z",
      "last_message_at": "2026-10-01T08:15:00Z",
      "window_expires_at": "2026-10-01T08:15:00Z",
      "contact_name": "string",
      "contact_handle": "string"
    }
  }
}

conversation.stage_changed

Coming soon A conversation moved to another lifecycle stage.

{
  "id": "evt_2Nq8Ld",
  "type": "conversation.stage_changed",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "conversation": {
      "id": "cv_3PzA91",
      "contact_id": "string",
      "channel_id": "string",
      "channel_type": "whatsapp",
      "status": "open",
      "stage_id": "string",
      "assignee_id": "string",
      "team_id": "string",
      "controller": "human",
      "unread_count": 0,
      "tags": [
        "string"
      ],
      "last_customer_at": "2026-10-01T08:15:00Z",
      "last_message_at": "2026-10-01T08:15:00Z",
      "window_expires_at": "2026-10-01T08:15:00Z",
      "contact_name": "string",
      "contact_handle": "string"
    }
  }
}

contact.created

Coming soon A contact was created.

{
  "id": "evt_2Nq8Ld",
  "type": "contact.created",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "contact": {
      "id": "ct_8Jk2Lm",
      "name": "Sara Al-Mutairi",
      "identities": [
        {
          "channel_type": null,
          "identifier": null,
          "display_name": null
        }
      ],
      "email": "string",
      "language": "ar",
      "dialect": "kuwaiti",
      "vip": true,
      "blocked": true,
      "tags": [
        "vip"
      ],
      "stage_id": "customer",
      "consents": {},
      "custom_fields": {},
      "last_activity_at": "2026-10-01T08:15:00Z"
    }
  }
}

contact.updated

Coming soon A contact’s details, tags or stage changed.

{
  "id": "evt_2Nq8Ld",
  "type": "contact.updated",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "contact": {
      "id": "ct_8Jk2Lm",
      "name": "Sara Al-Mutairi",
      "identities": [
        {
          "channel_type": null,
          "identifier": null,
          "display_name": null
        }
      ],
      "email": "string",
      "language": "ar",
      "dialect": "kuwaiti",
      "vip": true,
      "blocked": true,
      "tags": [
        "vip"
      ],
      "stage_id": "customer",
      "consents": {},
      "custom_fields": {},
      "last_activity_at": "2026-10-01T08:15:00Z"
    }
  }
}

template.status_updated

Beta Meta approved, rejected, paused or disabled a template.

{
  "id": "evt_2Nq8Ld",
  "type": "template.status_updated",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "name": "string",
    "language": "ar",
    "category": "marketing",
    "components": [
      {
        "type": "header",
        "format": "text",
        "text": "string",
        "examples": [],
        "buttons": []
      }
    ],
    "id": "tpl_Qm81",
    "status": "draft",
    "rejection_reason": "string",
    "quality": "GREEN",
    "updated_at": "2026-10-01T08:15:00Z"
  }
}

channel.status_updated

Coming soon A channel connected, disconnected, or its quality rating changed.

{
  "id": "evt_2Nq8Ld",
  "type": "channel.status_updated",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "id": "ch_wa_7Yt2",
    "type": "whatsapp",
    "status": "connected",
    "name": "Diet Station",
    "display_phone": "+965 2200 1234",
    "verified_name": "string",
    "quality": "GREEN",
    "waba_id": "string",
    "phone_number_id": "string",
    "created_at": "2026-10-01T08:15:00Z"
  }
}

broadcast.completed

Coming soon A broadcast finished sending.

{
  "id": "evt_2Nq8Ld",
  "type": "broadcast.completed",
  "created_at": "2026-10-01T08:15:00Z",
  "workspace_id": "string",
  "api_version": "2026-10-01",
  "data": {
    "name": "string",
    "channel_id": "string",
    "template": {
      "name": "string",
      "language": "string"
    },
    "audience": {
      "tags": [
        "string"
      ],
      "stage_id": "string",
      "recipients": [
        {
          "to": null,
          "params": null
        }
      ]
    },
    "send_at": "2026-10-01T08:15:00Z",
    "id": "bc_R2d9",
    "status": "scheduled",
    "counts": {
      "total": 0,
      "sent": 0,
      "delivered": 0,
      "read": 0,
      "replied": 0,
      "failed": 0
    }
  }
}