Skip to content

Webhooks

Events

How events reach your webhook, the envelope and the catalog of types.

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.

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.

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’s value reduced to this fact: the messages array (or statuses, or message_echoes) with a single element, and the matching metadata and contacts untouched. On Instagram and Messenger it is the messaging[] 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:

format: normalized
{
"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"
}
}
}
format: meta
{
"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.

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 WhatsApp
call.sdp_answer the contact picked up one of your calls (with the answer sdp) yes WhatsApp
call.status the call changed state (RINGING, ACCEPTED, REJECTED) yes WhatsApp
call.ended the call ended, with end_reason and the duration in duration_s yes WhatsApp
call.permission_updated the contact’s call permission changed (status, expires_at) yes WhatsApp
group.created · group.create_failed Meta created (or did not create) a group null WhatsApp
group.settings_updated · group.participants_updated · group.join_requested the group’s data or participants changed, or a join request arrived null WhatsApp
group.suspended · group.unsuspended · group.deleted the group was suspended, released or deleted null WhatsApp
flow.response the contact finished a Flow (with response and flow_token) yes WhatsApp
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 WhatsApp
order.received · order.updated a cart arrived or an order changed (charge, status, payment) yes WhatsApp
payment.updated Meta reported an order payment yes WhatsApp
template.status Meta approved, rejected or paused a template null WhatsApp
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 WhatsApp
history.batch batch of the 6-month history imported under coexistence null WhatsApp
contacts.sync contacts synced from the app under coexistence null WhatsApp
comment.received a comment (or a reply to a comment) arrived on a post or live of the account null Instagram
comment.replied you replied to a comment in public null Instagram
comment.private_replied you sent a private reply to a comment (comes with the message and the contact) null Instagram
comment.hidden · comment.unhidden you hid a comment or showed it again null Instagram
comment.deleted you deleted a comment null Instagram
mention.received the account was mentioned in a comment, caption or story (source) null Instagram
publication.published a publication went out, with external_media_id and permalink null Instagram
publication.failed a publication failed, with the reason in publication.error null Instagram
campaign.scheduled · campaign.started · campaign.completed · campaign.canceled a campaign was scheduled, started, finished or was canceled (data.campaign with status and numbers) null WhatsApp
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 WhatsApp
campaign.progress the campaign’s numbers changed (at most 1 per minute) null WhatsApp
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.

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 held status. When it comes back, they go out in the order the events were created (queue order); within a conversation, sequence applies.
  • A held delivery older than 15 days becomes failed with the org_suspended error.

Two groups of events do not belong to a single connection:

  • WABA events (template.*, flow.status_changed, flow.endpoint_alert and flow.endpoint_error; not flow.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 as org.standing_changed): they have no connection, so they only reach global destinations whose filter includes them (org.* or *). A connection destination never receives them.

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).

  • Delivery is at least once: the same event may arrive more than once. Deduplicate by Messajo-Event-Id (equal to the envelope id).
  • Events may arrive out of order, including across deliveries and redeliveries. Within a conversation, use sequence to order them: it only grows.
  • Respond 2xx fast 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.
  • Success = a 2xx response 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
  • Once the attempts run out, the delivery becomes failed and goes to the destination’s failure list in the panel.
  • Redeliver creates a new delivery of the same event (same Messajo-Event-Id, new Messajo-Delivery-Id, attempt 1). 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-failed with since (and until, optional). Each call queues up to 1000 failures and returns { queued, has_more }: with has_more: true, call again.
  • Deliveries and events are kept for 30 days.
  • 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. Any 2xx resets the count.
  • On pause, the destination’s deliveries still in progress become failed with the destination_paused error, and the organization’s owners and admins get an email.
  • While the destination is paused (automatically or by you), each new event creates a failed delivery with destination_paused. Nothing is lost: after fixing the endpoint and resuming the destination, redeliver the failures of that period.

Each destination receives only what you choose:

  • by event: a list of patterns. Accepted: * (everything), <family>.* (for example message.* or connection.*) and the exact type (for example message.status). A pattern that is not a known type nor a known or reserved family is rejected with validation_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: normalized or meta.

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.

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.