Receive messages
Get the messages people send to your Numbers through webhooks or an event stream.
When someone messages one of your Numbers, Polymorfa emits a message.received event. Deliver it to an HTTPS endpoint with a webhook, or read it over a server-sent event stream from your server. Both carry the same event with the same ID.
Before you begin#
- A connected Number in a project.
- For webhooks: a public HTTPS endpoint, and a credential with
webhooks:manageor a team owner or admin in the Console. - For event streams: a credential with
events:listen. Event streams require access.
Subscribe a webhook#
Console
- Select the project and open Settings → Webhooks.
- Add an endpoint with your public URL.
- Expand the
messageevents and selectmessage.received. - Save, then store the signing secret shown in the confirmation dialog. The Console never shows it again.
Only team owners and admins can add endpoints. See Manage webhooks in the Console.
API
Create a project webhook with Create project webhook:
curl -X POST "https://api.polymorfa.com/platform/projects/$PROJECT_ID/webhooks" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Idempotency-Key: create-inbox-webhook-1" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/polymorfa/webhook",
"eventTypes": ["message.received", "message.ack"],
"format": "native"
}'The response returns the signing secret once. Store it before you discard the response.
The Graph API does not create Polymorfa webhooks. For a Graph integration, create this webhook with "format": "meta" to receive Meta's object/entry/changes/value envelope, signed with X-Hub-Signature-256, from both connection types. See Delivery formats.
Verify and read the event#
Every delivery carries an x-webhook-signature header. Verify it against the exact request bytes before you parse the body; parsing and re-serializing the JSON changes the bytes. The TypeScript SDK does both:
import { isEvent, webhooks } from "@polymorfa/sdk";
export async function handleWebhook(body: ArrayBuffer, signature: string, secret: string) {
const event = await webhooks.verify({ body, signature, secret });
if (isEvent(event, "message.received")) {
console.log(event.session, event.payload.conversation, event.payload.type);
}
}The event body has this shape:
{
"id": "…",
"session": "739182640518203",
"timestamp": "2026-10-19T10:05:00.000Z",
"event": "message.received",
"payload": {
"id": "739182640518977",
"whatsapp_ids": { "linked_devices": "3EB0C767D8A1A2B5" },
"conversation": { "id": "739182640518203", "phoneNumber": "+15550001111" },
"fromMe": false,
"isGroup": false,
"pushName": "Ana",
"timestamp": 1792405500,
"type": "text",
"text": "Is my order on its way?"
}
}| Field | Meaning |
|---|---|
id | The event ID. Deduplicate with it; retries reuse it. |
session | The Number ID that received the message. |
payload.id | The message ID. Use it to reply, react or mark it seen. |
payload.conversation | Who sent it: id, and phoneNumber, bsuid or username when known. Group messages add conversation.sender. |
payload.type | text, image, video, audio, document, location, contact, sticker, sticker_pack, poll, reaction, button_reply, list_reply, native_flow_response, phone_number_shared, revoke, edited or unknown. |
payload.timestamp | When the message was sent, in Unix seconds. Meta Cloud API Numbers send it as a decimal string. |
The remaining payload fields depend on type: text, caption, mimeType, media, replyChoice, nativeFlowResponse, parentMessageId for a quoted message, and others. Meta Cloud API payloads also carry senderName, interactive, order and referral. See the message.received reference for every field, and Media previews and HD images for media details.
Respond to the delivery#
- Return any
2xxonly after you have durably accepted the event. - Store processed event IDs and skip repeats. Deliveries are retried and can arrive out of order.
- Do not log raw bodies: they contain message content.
To reply, send to the received payload.conversation.id and quote payload.id if you want. See Send messages.
Read events from a stream#
Open a stream from your server instead of, or beside, a webhook:
curl -N "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events/stream?types=message.received" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Accept: text/event-stream"Each event message holds the same event ID as the webhook. Its body is present only when hosted message storage is on for the Number; otherwise payload is null. Resume after a disconnect with the last cursor. See Stream events in real time.
Test it#
Send a message to the Number from another phone, or between two test numbers in the same project, and confirm your handler logs the event. To send a signed sample to your endpoint without a message, see Send a test delivery.
Related events#
| Event | When |
|---|---|
message.update, message.edited, message.revoked, message.delete | A received message changed or was removed. |
message.reaction, message.vote | Someone reacted or voted in a poll. |
message.echo | A coexistence Number sent a message from the WhatsApp Business app. |
message.sent, message.ack, message.failed | Delivery of messages you send. See Send messages. |
See also#
API version 2026-11-10 adds sticker packs and account sticker updates. These operations are a release candidate, unavailable in staging and production. See Stickers and sticker packs.