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.

Configure the webhook

Open the webhook settings

Go to Settings → API Keys & Webhooks and scroll to Message Status Webhook.

Enter your endpoint

Turn on Enable webhooks, enter your Webhook URL, and optionally an Authentication Token. The token is sent as Authorization: Bearer <token> on every request. After saving, the field shows (configured) and the token 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. Unticked statuses are dropped silently.

Save, then test

Click Save changes in the bar at the bottom; the page confirms “Webhook configuration saved.” Then click Test webhook. The test goes to the saved URL, so save before testing; a test sent before saving reports “Webhook configuration changed before the test delivery” or “No webhook URL configured”.

Status indicators

Indicator	Meaning
Inactive	Enable webhooks is off.
Not Tested	Enabled, but no delivery or test has happened yet.
Active	The most recent delivery or test succeeded.
Error	The most recent delivery or test failed. Check Last test and your server logs.
Last test	Pass or Fail with the 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 N/A until the first delivery.

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 successful with the response time. 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 Error.

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