Webhooks
Webhook Events
Every event you can subscribe to, with its JSON payload and field descriptions
Every delivery wraps the event’s payload in the same envelope:
Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Every event you can subscribe to, with its JSON payload and field descriptions
{
"eventId": "evt_0198f2a1-...",
"event": "contact.created",
"createdAt": "2026-09-09T18:26:19.671Z",
"data": { ... }
}
| Field | Description |
|---|---|
eventId | Unique id for this delivery. Use it to de-duplicate retried deliveries. |
event | The event name, matching one of the events below. |
createdAt | When the event was dispatched, in ISO 8601. |
data | The event-specific payload, documented below. |
{
"contact": {
"id": "b3f1...",
"organizationId": "a91c...",
"phone": "201234567890",
"name": "Ahmed Samir",
"createdAt": "2026-09-09T18:26:19.671Z",
"updatedAt": "2026-09-09T18:26:19.671Z"
}
}
| Field | Description |
|---|---|
contact | The full contact object as stored. |
{
"contact": {
"id": "b3f1...",
"organizationId": "a91c...",
"phone": "201234567890",
"name": "Ahmed Samir",
"updatedAt": "2026-09-09T18:26:19.671Z"
}
}
| Field | Description |
|---|---|
contact | The updated contact object. |
{
"contact": {
"id": "b3f1...",
"organizationId": "a91c..."
}
}
| Field | Description |
|---|---|
contact | The identifiers of the deleted contact. |
{
"conversationId": "c771...",
"contactId": "b3f1...",
"messages": [
{
"id": "m001...",
"conversationId": "c771...",
"direction": "inbound",
"type": "text",
"text": "Hello!",
"createdAt": "2026-09-09T18:26:19.671Z"
}
]
}
| Field | Description |
|---|---|
conversationId | The conversation the message belongs to. |
contactId | The contact on the other end of the conversation, or null if unresolved. |
messages | One or more message objects created together (e.g. a media message with a caption). |
{
"message": {
"id": "m001...",
"organizationId": "a91c...",
"status": "delivered",
"updatedAt": "2026-09-09T18:26:19.671Z"
}
}
| Field | Description |
|---|---|
message | The message with its updated status. |
{
"template": {
"id": "t001...",
"wabaId": "w001...",
"name": "order_confirmation",
"language": "en",
"status": "PENDING",
"category": "MARKETING",
"bodyText": "Your order {{1}} has been confirmed."
}
}
| Field | Description |
|---|---|
template | The full template object as created, prior to Meta review. |
{
"template": {
"templateId": "t001...",
"organizationId": "a91c...",
"status": "APPROVED",
"rejectionReason": null
}
}
| Field | Description |
|---|---|
template.status | The new status: APPROVED, REJECTED, or PENDING. |
template.rejectionReason | Present only when status is REJECTED. |
{
"template": {
"templateId": "t001...",
"organizationId": "a91c...",
"qualityScore": "GREEN"
}
}
| Field | Description |
|---|---|
template.qualityScore | GREEN, YELLOW, or RED. |
{
"template": {
"templateId": "t001...",
"organizationId": "a91c...",
"category": "UTILITY"
}
}
| Field | Description |
|---|---|
template.category | The template’s new category. |
{
"id": "t001..."
}
| Field | Description |
|---|---|
id | The id of the deleted template. |
{
"channelId": "ch001...",
"status": "CONNECTED",
"isConnected": true,
"reason": null,
"label": "Support Line",
"platformId": "1590000000000"
}
| Field | Description |
|---|---|
channelId | The channel whose status changed. |
status | The new channel status. |
isConnected | Whether the channel is currently connected. |
reason | Why the status changed, when applicable. |
label | The channel’s display name. |
platformId | The WhatsApp phone number id on Meta’s side. |
{
"channelId": "ch001..."
}
| Field | Description |
|---|---|
channelId | The id of the deleted channel. |
{
"channelIds": ["ch001...", "ch002..."],
"violationType": "SPAM_RATE_LIMIT"
}
| Field | Description |
|---|---|
channelIds | Channels affected by the violation. |
violationType | The kind of violation Meta reported. |
{
"channelIds": ["ch001..."],
"restrictions": [
{
"type": "MESSAGING_LIMIT",
"description": "Daily conversation limit reduced",
"expiration": 1717430460,
"remediation": "Improve quality rating to lift the limit"
}
]
}
| Field | Description |
|---|---|
channelIds | Channels the restrictions apply to. |
restrictions[].type | The kind of restriction Meta applied. |
restrictions[].description | Human-readable explanation. |
restrictions[].expiration | Unix timestamp the restriction lifts at. |
restrictions[].remediation | What to do to lift the restriction, when known. |
{
"broadcastId": "br001...",
"total": 500,
"sent": 486,
"failed": 14,
"skipped": 0,
"sentAt": "2026-09-09T18:26:19.671Z",
"channelName": "Support Line",
"status": "SENT"
}
| Field | Description |
|---|---|
total | The audience size. |
sent | Messages delivered successfully. |
failed | Messages that failed to send. |
skipped | Contacts excluded before sending (no phone, unreachable, …). |
status | SENT for this event; broadcasts with 0 sent and some failed are reported on broadcast.failed instead. |
{
"broadcastId": "br001...",
"errorMessage": "No sendable contacts found in this audience."
}
| Field | Description |
|---|---|
broadcastId | The broadcast that failed. |
errorMessage | Human-readable reason for the failure. |
{
"id": "br001..."
}
| Field | Description |
|---|---|
id | The id of the deleted broadcast. |