# WhatsApp webhook events

Every event here can also reach agents as an MCP event through Hookdeck: [MCP events](https://hookdeck.com/webhooks/whatsapp/mcp-events).

Agent skill: `npx skills add hookdeck/webhook-skills --skill whatsapp-webhooks` ([details](https://hookdeck.com/webhooks/whatsapp/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [WhatsApp's official docs](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks).

[Overview](https://hookdeck.com/webhooks/whatsapp) · [Webhook events (29)](https://hookdeck.com/webhooks/whatsapp/events) · [MCP events](https://hookdeck.com/webhooks/whatsapp/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/whatsapp/verify) · [Production guide](https://hookdeck.com/webhooks/whatsapp/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/whatsapp/skill)

## account

### account_alerts

Confidence: documented · Schema: from WhatsApp docs (example)

Alert on messaging limits, profile photo or Official Business Account status

Identified by: entry[].changes[].field field in the body · Object: `account`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/account-alerts.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/account-alerts.json)

### account_review_update

Confidence: documented · Schema: from WhatsApp docs (example)

WhatsApp account review against policy finishes or is deferred

Identified by: entry[].changes[].field field in the body · Object: `account`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/account-review-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/account-review-update.json)

### account_settings_update

Confidence: documented · Schema: No payload yet

[Listed in WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override)

Identified by: entry[].changes[].field field in the body · Object: `account`

No payload yet.

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/account-settings-update.json)

### account_update

Confidence: documented · Schema: from WhatsApp docs (example)

Verification, sharing, policy or deletion change on a Messaging account

Identified by: entry[].changes[].field field in the body · Object: `account`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/account-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/account-update.json)

### business_capability_update

Confidence: documented · Schema: from WhatsApp docs (example)

Messaging or phone number limits change, or a Messaging account is created

Identified by: entry[].changes[].field field in the body · Object: `account`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/business-capability-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/business-capability-update.json)

## business_app

### history

Confidence: documented · Schema: from WhatsApp docs (example)

Partner syncs a WhatsApp Business app customer's chat history

Identified by: entry[].changes[].field field in the body · Object: `business_app`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/history.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/history.json)

### smb_app_state_sync

Confidence: documented · Schema: from WhatsApp docs (example)

Onboarded WhatsApp Business app contacts sync or change

Identified by: entry[].changes[].field field in the body · Object: `business_app`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/smb-app-state-sync.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/smb-app-state-sync.json)

### smb_message_echoes

Confidence: documented · Schema: from WhatsApp docs (example)

Onboarded business sends, edits or deletes a message in the app

Identified by: entry[].changes[].field field in the body · Object: `business_app`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/smb-message-echoes.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/smb-message-echoes.json)

## group

### group_lifecycle_update

Confidence: documented · Schema: from WhatsApp docs (example)

Group is created or deleted

Identified by: entry[].changes[].field field in the body · Object: `group`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-lifecycle-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-lifecycle-update.json)

### group_participants_update

Confidence: documented · Schema: from WhatsApp docs (example)

Group participants join, leave, are removed or request to join

Identified by: entry[].changes[].field field in the body · Object: `group`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-participants-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-participants-update.json)

### group_settings_update

Confidence: documented · Schema: official schema

Group settings are updated

Identified by: entry[].changes[].field field in the body · Object: `group`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-settings-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-settings-update.json)

### group_status_update

Confidence: documented · Schema: from WhatsApp docs (example)

Group is suspended or its suspension clears

Identified by: entry[].changes[].field field in the body · Object: `group`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-status-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/group-status-update.json)

## messaging

### automatic_events

Confidence: documented · Schema: from WhatsApp docs (example)

Purchase or lead detected in a Click to WhatsApp ad chat

Identified by: entry[].changes[].field field in the body · Object: `messaging`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/automatic-events.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/automatic-events.json)

### calls

Confidence: documented · Schema: from WhatsApp docs (example)

Call connects, changes status or ends

Identified by: entry[].changes[].field field in the body · Object: `messaging`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/calls.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/calls.json)

### consumer_profile

Confidence: documented · Schema: No payload yet

[Listed in WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override)

Identified by: entry[].changes[].field field in the body · Object: `messaging`

No payload yet.

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/consumer-profile.json)

### message_echoes

Confidence: documented · Schema: No payload yet

[Listed in WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override)

Identified by: entry[].changes[].field field in the body · Object: `messaging`

No payload yet.

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/message-echoes.json)

### messages

Confidence: documented · Schema: from WhatsApp docs (example)

User sends a message, or a message you sent changes status

Identified by: entry[].changes[].field field in the body · Object: `messaging`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/messages.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/messages.json)

### messaging_handovers

Confidence: documented · Schema: No payload yet

[Listed in WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override)

Identified by: entry[].changes[].field field in the body · Object: `messaging`

No payload yet.

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/messaging-handovers.json)

### standby

Confidence: documented · Schema: No payload yet

[Listed in WhatsApp docs](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override)

Identified by: entry[].changes[].field field in the body · Object: `messaging`

No payload yet.

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/standby.json)

### user_preferences

Confidence: documented · Schema: from WhatsApp docs (example)

User stops or resumes marketing messages

Identified by: entry[].changes[].field field in the body · Object: `messaging`

```json
{
  "object": "whatsapp_business_account",
  "entry": [ … ]
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/user-preferences.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/user-preferences.json)

## phone_number

### phone_number_name_update

Confidence: documented · Schema: from WhatsApp docs (example)

Display name review finishes for a business phone number

Identified by: entry[].changes[].field field in the body · Object: `phone_number`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/phone-number-name-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/phone-number-name-update.json)

### phone_number_quality_update

Confidence: documented · Schema: from WhatsApp docs (example)

Business phone number's throughput level changes

Identified by: entry[].changes[].field field in the body · Object: `phone_number`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/phone-number-quality-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/phone-number-quality-update.json)

### security

Confidence: documented · Schema: from WhatsApp docs (example)

Business phone number's PIN or two-step verification changes

Identified by: entry[].changes[].field field in the body · Object: `phone_number`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/security.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/security.json)

## template

### message_template_components_update

Confidence: documented · Schema: from WhatsApp docs (example)

Template's components are edited

Identified by: entry[].changes[].field field in the body · Object: `template`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/message-template-components-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/message-template-components-update.json)

### message_template_quality_update

Confidence: documented · Schema: from WhatsApp docs (example)

Template's quality score changes

Identified by: entry[].changes[].field field in the body · Object: `template`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/message-template-quality-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/message-template-quality-update.json)

### message_template_status_update

Confidence: documented · Schema: from WhatsApp docs (example)

Template is approved, rejected, disabled, archived or unarchived

Identified by: entry[].changes[].field field in the body · Object: `template`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/message-template-status-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/message-template-status-update.json)

### template_category_update

Confidence: documented · Schema: from WhatsApp docs (example)

Template's category changes, or is about to change

Identified by: entry[].changes[].field field in the body · Object: `template`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/template-category-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/template-category-update.json)

## Other WhatsApp events

### partner_solutions

Confidence: documented · Schema: from WhatsApp docs (example)

Multi-Partner Solution changes status

Identified by: entry[].changes[].field field in the body · Object: `partner_solutions`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/partner-solutions.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/partner-solutions.json)

### payment_configuration_update

Confidence: documented · Schema: from WhatsApp docs (example)

Payment configuration connects, disconnects or becomes active

Identified by: entry[].changes[].field field in the body · Object: `payment_configuration_update`

```json
{
  "entry": [ … ],
  "object": "whatsapp_business_account"
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/whatsapp/events/payment-configuration-update.json)

[View as JSON](https://hookdeck.com/webhooks/whatsapp/events/payment-configuration-update.json)

---

Not affiliated with WhatsApp. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/whatsapp.json) · [Report a correction](https://hookdeck.com/contact)
