Message Status Webhooks - Popcorn Documentation

When you send a template through POST /api/v2/template/send, Popcorn tracks that message and calls your webhook URL each time WhatsApp reports a new status: sent, delivered, read, or failed. You get delivery status in real time without polling. Webhooks are sent only for messages sent through the /api/v2 endpoint. Messages sent through the standard /template/send endpoint, from campaigns, or from the Inbox do not trigger them.

Before you start

An HTTPS endpoint that accepts POST requests with a JSON body and answers with a 2xx status within 10 seconds. Plain http:// URLs, localhost, and private network addresses are rejected.
A role that can edit settings. By default only the Owner and Admin roles can change webhook configuration or run a test. Managers see the panel read-only, with “Only people who can edit workspace settings can change these.”

Configure the webhook

Open the webhook settings

Go to Settings → API keys and webhooks and find the Message status webhook panel (“Get a request on your server whenever a message changes status.”).

Enter your endpoint

Turn on Send status updates, enter your Webhook URL (“We send each status change to this URL.”), and optionally an Authentication token. The token is sent as Authorization: Bearer <token> on every request. Once one is saved, the field reads “A token is saved.” and is never displayed again; enter a new value to replace it.

Choose the events

Under Events to send, tick the statuses you want: Sent, Delivered, Read, Failed. All four are on by default, and you need at least one (“Pick at least one event.”). Unticked statuses are dropped silently.

Save, then test

Click Save changes in the Unsaved changes bar; you see Webhook saved. Then click Test webhook at the foot of the panel. It is unavailable until your changes are saved (“Save your changes to test the new URL.”) and until a URL is saved (“Save a URL to send a test.”). The test goes to the saved URL.

Status indicators

Indicator	Meaning
Inactive	Send status updates is off.
Not tested	Enabled, but no delivery or test has happened yet.
Active	The most recent delivery or test succeeded.
Test failed	The most recent delivery or test failed. Check Last test and your server logs.
Last test	”Passed on” or “Failed on” with the date and time of the last test. This row and Success rate appear only after you have run Test webhook at least once.
Success rate	Successful deliveries divided by all real deliveries since the webhook was configured. Test requests are not counted. Shown as No tests yet until the first delivery.

The panel also shows an Example payload, a short sample of what your server receives.

Test payload

Test webhook sends one request, with no retries, and waits up to 10 seconds. It uses the User-Agent Popcorn-Webhook-Test/1.0 and placeholder values so you can tell it apart from real traffic:

{
  "version": "1.0",
  "messageId": "test-1725184200000",
  "toNumber": "test-recipient",
  "fromNumber": "test-sender",
  "timestamp": "2026-09-01T10:30:00+0000",
  "status": "whatsapp_sent",
  "providerMessageId": "test-wamid",
  "statusCode": 0,
  "reason": "Test webhook"
}

A successful test shows Test passed with “Responded in N ms”. A failed test shows Test failed with the reason, for example when the URL points to a private address.

Webhook payload

Each status update is a POST to your URL with these headers:

Content-Type: application/json
User-Agent: Popcorn-Webhook/1.0
Authorization: Bearer <your-authentication-token>

The Authorization header is present only when you configured a token.

{
  "version": "1.0",
  "messageId": "my-tracking-id-001",
  "toNumber": "971501234567",
  "fromNumber": "971509876543",
  "timestamp": "2026-09-01T10:30:00+0000",
  "status": "whatsapp_delivered",
  "providerMessageId": "wamid.HBgNOTcxNT...",
  "statusCode": 0,
  "reason": "Message processed successfully"
}

Field	Type	Description
`version`	string	Payload version, currently `"1.0"`.
`messageId`	string	The `messageId` you sent in the request, or the one Popcorn generated (`msg-...`) if you omitted it. Use it to match the event to your record.
`toNumber`	string	The recipient number from your request.
`fromNumber`	string	The `fromNumber` from your request. If you did not send one, this is the literal string `"default"`.
`timestamp`	string	When Popcorn created the notification, in UTC, formatted `yyyy-MM-ddTHH:mm:ss+0000`.
`status`	string	`whatsapp_sent`, `whatsapp_delivered`, `whatsapp_read`, or `whatsapp_failed`.
`providerMessageId`	string	WhatsApp’s message ID (`wamid`).
`statusCode`	number	`0` for every non-failure status; an error code for `whatsapp_failed` (see below).
`errorMessage`	string	Present only on `whatsapp_failed`: the error details WhatsApp returned, as a JSON string.
`reason`	string	`"Message processed successfully"` on success, or the same text as `errorMessage` on failure.

Status events

You receive one request per status update WhatsApp reports. A delivered message typically produces whatsapp_sent, then whatsapp_delivered, then whatsapp_read; a message that fails produces whatsapp_failed. Popcorn relays statuses as WhatsApp reports them, so a message does not always receive every status, and a failure may arrive without a prior whatsapp_sent.

Status	Meaning
`whatsapp_sent`	WhatsApp accepted the message.
`whatsapp_delivered`	The message reached the recipient’s device.
`whatsapp_read`	The recipient opened the message.
`whatsapp_failed`	WhatsApp could not deliver the message. Read `errorMessage`.

Error codes

For whatsapp_failed, Popcorn derives statusCode from keywords in WhatsApp’s error text. When no keyword matches, the code is 9988.

Code	Name	Set when the error text mentions
`2006`	User blocked	”blocked”
`2008`	Message expired	”expired”
`2009`	Message undelivered	”undelivered” or “not delivered”
`2014`	Max retries exhausted	”retry” or “retries”
`2024`	User not opted in	”not opted in” or “opt-in”
`9988`	Generic error	Anything else.

Example failure:

{
  "version": "1.0",
  "messageId": "my-tracking-id-002",
  "toNumber": "971501234567",
  "fromNumber": "default",
  "timestamp": "2026-09-01T10:35:00+0000",
  "status": "whatsapp_failed",
  "providerMessageId": "wamid.HBgNOTcxNT...",
  "statusCode": 9988,
  "errorMessage": "[{\"code\":131026,\"title\":\"Message undeliverable\"}]",
  "reason": "[{\"code\":131026,\"title\":\"Message undeliverable\"}]"
}

Retries and timeouts

Popcorn treats any 2xx response as success. Anything else, including a timeout after 10 seconds, is a failed attempt.

Attempt	Delay before it
1st	Immediate
2nd	1 second
3rd (final)	3 seconds

Popcorn does not retry when your endpoint answers with a 4xx status, except 408 and 429, which are retried like network errors. After the final failure the event is dropped: it is not queued or resent later. The failure is recorded on the message, counts against Success rate, and switches the indicator to Test failed.

Return 2xx as soon as you have stored the payload, and process it afterwards. A handler that takes longer than 10 seconds is treated as failed and retried, so you may receive the same event again.

Verifying requests

Configure an Authentication token and reject any request whose Authorization header does not carry it. Popcorn does not sign payloads; the bearer token is the only way to confirm a request came from Popcorn.

Send a template: the /api/v2 request that creates the tracking record, including messageId and metadata.
Delivery and reachability: what sent, delivered, read, and failed mean for WhatsApp messages in general.

​Before you start

​Configure the webhook

​Status indicators

​Test payload

​Webhook payload

​Status events

​Error codes

​Retries and timeouts

​Verifying requests

​Related

Before you start

Configure the webhook

Status indicators

Test payload

Webhook payload

Status events

Error codes

Retries and timeouts

Verifying requests

Related