Webhooks
Events
How events reach your webhook, the envelope and the catalog of types.
How it arrives
Section titled “How it arrives”Each event arrives as a POST with a JSON body to the URL you registered as a destination. The headers of every delivery:
| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
Messajo-Webhooks/1 |
Messajo-Signature |
t=<unix s>,v1=<hex> — see Verify the signature |
Messajo-Event-Id |
event id (evt_…), the same across all attempts and redeliveries |
Messajo-Event-Type |
event type, for example message.received |
Messajo-Delivery-Id |
id of this delivery to this destination (dlv_…). A redelivery creates a new delivery, with a new id |
Messajo-Delivery-Attempt |
attempt number of this delivery, starting at 1 |
The custom headers you set on the destination are sent too. They never override the Messajo-* ones, and Host, Content-Type, Content-Length, User-Agent, Transfer-Encoding and Connection cannot be set.
Envelope
Section titled “Envelope”Every event comes in the same envelope:
| Field | Type | What it is |
|---|---|---|
id |
string |
event id (evt_…). Use it to drop duplicates. |
type |
string |
event type, for example message.received. |
format |
"normalized" | "meta" |
format used in data (see below). |
org |
string |
organization id. |
connection |
string | null |
connection id (conn_…); null on organization events such as destination.test. |
channel |
"whatsapp" | "instagram" | "messenger" | null |
the connection’s channel; null when connection is null. |
timestamp |
string |
date and time of the fact, ISO 8601 in UTC. |
sequence |
number | null |
increasing per conversation; null on events outside a conversation (see the catalog). |
data |
object |
the event content, in the format given by format. |
The two formats
Section titled “The two formats”Each destination picks a format:
normalized: Messajo’s format, the same across channels, in snake_case.meta: the piece of the Meta webhook that produced the event. On WhatsApp it is the change’svaluereduced to this fact: themessagesarray (orstatuses, ormessage_echoes) with a single element, and the matchingmetadataandcontactsuntouched. On Instagram and Messenger it is themessaging[]item.
An event that does not come from a Meta webhook (for example message.sent and destination.test) has no meta version: it goes out as normalized even to a meta destination. That is why format tells the format that was used, not the one the destination asked for. Check format before reading data.
The same message.received in both formats:
{ "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB", "type": "message.received", "format": "normalized", "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y", "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS", "channel": "whatsapp", "timestamp": "2026-11-09T14:03:27.000Z", "sequence": 42, "data": { "contact": { "display_name": "Maria", "id": "ctc_01JC9W3X5R1P0N9M8L7K6J5H4G", "identities": [{ "kind": "wa_id", "scope": "", "value": "5511999999999" }] }, "conversation": { "extended_window_ends_at": null, "id": "cnv_01JC9W3X5S2Q1P0N9M8L7K6J5H", "window_ends_at": "2026-11-10T14:03:27.000Z" }, "message": { "content": { "body": "Hi! Has my order shipped?", "type": "text" }, "context": null, "direction": "inbound", "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA", "id": "msg_01JC9W3X6T3R2Q1P0N9M8L7K6J", "source": "customer", "timestamp": "2026-11-09T14:03:27.000Z" } }}{ "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB", "type": "message.received", "format": "meta", "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y", "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS", "channel": "whatsapp", "timestamp": "2026-11-09T14:03:27.000Z", "sequence": 42, "data": { "contacts": [{ "profile": { "name": "Maria" }, "wa_id": "5511999999999" }], "messages": [ { "from": "5511999999999", "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA", "text": { "body": "Hi! Has my order shipped?" }, "timestamp": "1762697007", "type": "text" } ], "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511988887777", "phone_number_id": "106540352242922" } }}The keys of data come in alphabetical order and the same event always produces the same bytes, on every attempt. Even so, verify the signature over the raw body, never over re-serialized JSON. The API reference has the full schema of each data.
Catalog
Section titled “Catalog”| Type | When | sequence |
Channels |
|---|---|---|---|
message.received |
a message from the contact arrived | yes | all |
message.sent |
one of your messages was accepted by Meta | yes | all |
message.status |
the status of one of your messages changed (delivered, read, failed) | yes | all |
message.echo |
message sent outside the API (phone app, Meta Inbox) | yes | all |
message.edited |
the contact edited a message | yes | all |
message.revoked |
the contact deleted a message | yes | all |
call.incoming |
the contact is calling the number (with the offer sdp) |
yes | |
call.sdp_answer |
the contact picked up one of your calls (with the answer sdp) |
yes | |
call.status |
the call changed state (RINGING, ACCEPTED, REJECTED) |
yes | |
call.ended |
the call ended, with end_reason and the duration in duration_s |
yes | |
call.permission_updated |
the contact’s call permission changed (status, expires_at) |
yes | |
group.created · group.create_failed |
Meta created (or did not create) a group | null |
|
group.settings_updated · group.participants_updated · group.join_requested |
the group’s data or participants changed, or a join request arrived | null |
|
group.suspended · group.unsuspended · group.deleted |
the group was suspended, released or deleted | null |
|
flow.response |
the contact finished a Flow (with response and flow_token) |
yes | |
flow.status_changed · flow.endpoint_alert · flow.endpoint_error |
the Flow status changed, Meta raised an endpoint health alert, or the contact’s app reported an error | null |
|
order.received · order.updated |
a cart arrived or an order changed (charge, status, payment) | yes | |
payment.updated |
Meta reported an order payment | yes | |
template.status |
Meta approved, rejected or paused a template | null |
|
connection.created |
new active connection | null |
all |
connection.updated |
the status changed (to active, restricted or disabled), or the connection’s health or data changed; the reason comes in reason |
null |
all |
connection.disconnected |
the connection was turned off | null |
all |
connection.needs_reconnect |
access dropped and the connection must be redone | null |
all |
connection.error |
Meta reported an account or number error, outside a message (errors[]) |
null |
|
history.batch |
batch of the 6-month history imported under coexistence | null |
|
contacts.sync |
contacts synced from the app under coexistence | null |
|
comment.received |
a comment (or a reply to a comment) arrived on a post or live of the account | null |
|
comment.replied |
you replied to a comment in public | null |
|
comment.private_replied |
you sent a private reply to a comment (comes with the message and the contact) | null |
|
comment.hidden · comment.unhidden |
you hid a comment or showed it again | null |
|
comment.deleted |
you deleted a comment | null |
|
mention.received |
the account was mentioned in a comment, caption or story (source) |
null |
|
publication.published |
a publication went out, with external_media_id and permalink |
null |
|
publication.failed |
a publication failed, with the reason in publication.error |
null |
|
campaign.scheduled · campaign.started · campaign.completed · campaign.canceled |
a campaign was scheduled, started, finished or was canceled (data.campaign with status and numbers) |
null |
|
campaign.paused · campaign.resumed |
the campaign paused or resumed; reason gives the reason and auto: true when Messajo did it (including limit_reached, the 24-hour tier, and org_suspended, when the organization is suspended) |
null |
|
campaign.progress |
the campaign’s numbers changed (at most 1 per minute) | null |
|
org.standing_changed |
the organization’s standing changed (active, restricted or suspended), since 1.1.0 |
null |
— |
destination.test |
you clicked Test on the destination (or called POST /v1/destinations/{id}/test) |
null |
— |
Accepting, rejecting, ending and placing calls through the API: see WhatsApp calls.
message.sent and message.status carry campaign: { id, recipient_id } when the message came from a campaign, and null otherwise. message.* events carry group: { id, external_id, subject } on a group message (and null outside one) and the conversation type in conversation.kind.
message.status carries cost: { estimate, currency, rate_card_version } on the status that triggered a Meta charge and null on the others; see Meta costs.
Organization
Section titled “Organization”org.standing_changed tells you when the organization’s standing changes. reason is payment, abuse, manual or meta_request, and is null when the organization goes back to active.
{ "type": "org.standing_changed", "data": { "organization": { "id": "org_1", "standing": "suspended", "previous_standing": "restricted", "reason": "payment", "since": "2026-11-13T12:00:00.000Z" } }}- It is emitted before the organization’s webhooks are held and is never held itself: you always get the suspension notice.
- While the organization is suspended, deliveries get the
heldstatus. When it comes back, they go out in the order the events were created (queue order); within a conversation,sequenceapplies. - A
helddelivery older than 15 days becomesfailedwith theorg_suspendederror.
WABA and organization events
Section titled “WABA and organization events”Two groups of events do not belong to a single connection:
- WABA events (
template.*,flow.status_changed,flow.endpoint_alertandflow.endpoint_error; notflow.response, which belongs to the receiving number): Meta emits them for the WhatsApp Business account (WABA), which can hold several numbers. Messajo delivers the event to a destination of any connection on the same WABA, once per destination. The global destination receives it too, without duplicates. - Organization events (
org.*, such asorg.standing_changed): they have no connection, so they only reach global destinations whose filter includes them (org.*or*). A connection destination never receives them.
Connection reasons
Section titled “Connection reasons”The connection.* events carry the connection in data.connection, with status, previous_status and the reason in reason:
reason |
Status after | What happened |
|---|---|---|
reconnected |
active | The connection was redone (in the panel, by link, or because Meta reconnected the account) |
reinstated |
active | Meta reinstated the account after a violation or ban |
restriction_lifted |
active | Meta’s restriction ended |
account_restriction |
restricted | Meta restricted the account for a period |
policy_blocked |
restricted | Meta blocked a send due to policy (368 or 131031) |
violation:<type> |
disabled | Meta flagged a policy violation |
banned |
disabled | Meta banned the account |
token_invalid · meta_token_invalid |
needs reconnect | Meta invalidated the token (error 190), in a health read or a send |
partner_removed · partner_removed:<reason> |
disconnected | The account removed Messajo as a partner |
app_uninstalled |
disconnected | The app was uninstalled from the account |
account_deleted |
disconnected | The account or number was deleted at Meta |
offboarded |
disconnected | The account left Meta’s platform |
user_requested |
disconnected | Someone in the organization disconnected it in the panel or through the API |
billing_suspended |
disconnected | The organization was suspended for non-payment and its connections were disconnected |
token_expired |
needs reconnect | Legacy: no longer emitted (error 190 now becomes token_invalid) |
app_deauthorized |
disconnected (Instagram) · needs reconnect (Messenger) | The person who authorized removed the app in Meta’s settings |
data_deleted |
disconnected | The person asked Meta to delete their data and Messajo deleted the Instagram account data |
scheduled_for_disable |
unchanged | Meta scheduled the account to be disabled |
quality_changed |
unchanged | The number’s quality changed |
limit_changed |
unchanged | The messaging tier or the account capacity changed |
send_rate_changed |
unchanged | The speed changed (20, 80 or 1,000 msg/s) |
can_send_changed |
unchanged | Sending changed (available, limited or blocked) |
name_approved · name_rejected |
unchanged | Meta decided the display name change request |
alert |
unchanged | Meta sent an account alert |
dm_access_disabled |
unchanged | The Instagram account turned off access to messages outside the app (detected at connect or by the health check) |
resubscribed |
unchanged | The app had left the webhook subscription of the account or Page and Messajo subscribed again |
policy_enforcement |
restricted or active | Meta blocked or released the Page on Messenger due to policy |
When the status does not change, previous_status equals status. A status change also emails owners and admins (at most one per reason every 6 h).
Order and duplicates
Section titled “Order and duplicates”- Delivery is at least once: the same event may arrive more than once. Deduplicate by
Messajo-Event-Id(equal to the envelopeid). - Events may arrive out of order, including across deliveries and redeliveries. Within a conversation, use
sequenceto order them: it only grows. - Respond
2xxfast and process later (in a queue of your own). Heavy work inside the request makes the delivery time out and come back as a retry.
Retries and failures
Section titled “Retries and failures”- Success = a
2xxresponse within 10 seconds, in total. Anything else counts as a failure: another status, timeout, network error or blocked address. Redirects (3xx) are not followed and count as failures. - Messajo keeps the first 1024 bytes of the response of each attempt, for you to see in the panel.
- After a failure, it retries following the table below: 1 immediate attempt plus 14 more, over a little more than 23 hours. Each wait varies by ±10% and no attempt goes out later than 24 hours after the delivery was created.
| Attempt | Wait since the previous one | Since the 1st (approx.) |
|---|---|---|
| 1 | — | 0 |
| 2 | 10 s | 10 s |
| 3 | 30 s | 40 s |
| 4 | 1 min | 1 min 40 s |
| 5 | 2 min | 3 min 40 s |
| 6 | 5 min | 8 min 40 s |
| 7 | 10 min | 18 min 40 s |
| 8 | 20 min | 38 min 40 s |
| 9 | 40 min | 1 h 18 min |
| 10 | 1 h | 2 h 18 min |
| 11 | 2 h | 4 h 18 min |
| 12 | 3 h | 7 h 18 min |
| 13 | 4 h | 11 h 18 min |
| 14 | 6 h | 17 h 18 min |
| 15 | 6 h | 23 h 18 min |
Failure list and redelivery
Section titled “Failure list and redelivery”- Once the attempts run out, the delivery becomes
failedand goes to the destination’s failure list in the panel. - Redeliver creates a new delivery of the same event (same
Messajo-Event-Id, newMessajo-Delivery-Id, attempt1). It only works while the destination is active. - To redeliver many at once, use Redeliver failures in the panel or
POST /v1/destinations/{id}/redeliver-failedwithsince(anduntil, optional). Each call queues up to 1000 failures and returns{ queued, has_more }: withhas_more: true, call again. - Deliveries and events are kept for 30 days.
Automatic pause
Section titled “Automatic pause”- A destination is paused automatically (
auto_paused) when it piles up 10 failures in a row and has been failing for at least 24 hours. Any2xxresets the count. - On pause, the destination’s deliveries still in progress become
failedwith thedestination_pausederror, and the organization’s owners and admins get an email. - While the destination is paused (automatically or by you), each new event creates a
faileddelivery withdestination_paused. Nothing is lost: after fixing the endpoint and resuming the destination, redeliver the failures of that period.
Filters
Section titled “Filters”Each destination receives only what you choose:
- by event: a list of patterns. Accepted:
*(everything),<family>.*(for examplemessage.*orconnection.*) and the exact type (for examplemessage.status). A pattern that is not a known type nor a known or reserved family is rejected withvalidation_failed; - by connection: a connection destination receives only that connection’s events; a global destination (no connection) receives events from all of them. See Destination types;
- format:
normalizedormeta.
The event is delivered when some pattern matches the type and the destination accepts the event’s connection. destination.test skips the filters: it goes only to the tested destination, in a single attempt, even when the destination is paused.
Other destinations
Section titled “Other destinations”The webhook is the default destination. RabbitMQ, SQS, Kafka and WebSocket receive the same envelope, with the same signature, the same filters and the same retries: see Destination types.