Events

Available events

Entity	Operation	Trigger
`messages`	`insert`	A new message is created (incoming or outgoing)
`messages`	`update`	A message status changes (sent, delivered, read, failed)
`conversations`	`insert`	A new conversation is created
`conversations`	`update`	A conversation is updated (closed, reopened, assigned)

Message events

`messages` / `insert`

Fired when:

An incoming WhatsApp message is received
An outgoing message is sent (by a human agent or AI agent)

`messages` / `update`

Fired when:

A message status changes: sent → delivered → read
A message fails to send

Example: template message fails

If you send a template message and Meta rejects it, your webhook receives:

{
  "entity": "messages",
  "action": "update",
  "data": {
    "id": "2c184fe9-8618-4c35-a653-db59c274e4c5",
    "direction": "outgoing",
    "organization_id": "00438702-d4a3-4411-9141-21febf13acbb",
    "organization_address": "238013449404478",
    "contact_address": "5215551234567",
    "content": {
      "kind": "template",
      "type": "data",
      "data": {
        "name": "vinculacion_regulatoria",
        "language": { "code": "es" },
        "components": [
          { "type": "body", "parameters": [{ "type": "text", "text": "Juan" }] }
        ]
      }
    },
    "status": {
      "pending": "2026-05-14T01:55:14+00:00",
      "failed": "2026-05-14T01:55:15Z",
      "errors": [
        {
          "error": {
            "code": 132000,
            "type": "OAuthException",
            "message": "(#132000) Number of parameters does not match the expected number of params",
            "error_data": {
              "details": "body: number of localizable_params (0) does not match the expected number of params (1)"
            }
          }
        }
      ]
    }
  }
}

To detect failed messages in your webhook handler, check for data.status.failed:

app.post('/webhook', (req, res) => {
  const { entity, action, data } = req.body;

  if (entity === 'messages' && action === 'update' && data.status.failed) {
    const error = data.status.errors?.[0]?.error;
    console.error(`Message ${data.id} failed: [${error?.code}] ${error?.message}`);
    // Alert your team, retry with corrected params, etc.
  }

  res.sendStatus(200);
});

See Message Status > Common error codes for a reference of Meta error codes.

Conversation events

`conversations` / `insert`

Fired when:

A new conversation starts (first message from a new contact)
A conversation is created manually

`conversations` / `update`

Fired when:

A conversation is closed (24-hour window expires)
A conversation is reopened (new template sent)
An agent is assigned or unassigned

On this page