# 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](https://docs.polymorfa.com/numbers) in a project.
- For webhooks: a public HTTPS endpoint, and a credential with
  `webhooks:manage` or a team owner or admin in the Console.
- For event streams: a credential with `events:listen`. Event streams require
  access.

## Subscribe a webhook

**Console:**

1. Select the project and open **Settings → Webhooks**.
2. Add an endpoint with your public URL.
3. Expand the `message` events and select `message.received`.
4. 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](https://docs.polymorfa.com/development/webhooks#manage-webhooks-in-the-console).

**API:**

Create a project webhook with
[Create project webhook](https://docs.polymorfa.com/api/webhook-endpoints/create-project-webhook):

```bash
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](https://docs.polymorfa.com/development/webhooks#delivery-formats).

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Not supported.

The `subscribed_apps` methods, such as
[Subscribe a webhook app](https://docs.polymorfa.com/api/graph/webhooks/subscribe-a-webhook-app),
manage a Meta app's subscription to a WhatsApp Business Account. They don't
change where Polymorfa delivers events.

## 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:

```typescript
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:

```json
{
  "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](https://docs.polymorfa.com/api/events#message-received)
for every field, and [Media previews and HD images](https://docs.polymorfa.com/messaging/media) for
media details.

## Respond to the delivery

- Return any `2xx` only 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](https://docs.polymorfa.com/messaging/send#reply-mention-and-forward).

## Read events from a stream

Open a stream from your server instead of, or beside, a webhook:

```bash
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](https://docs.polymorfa.com/development/event-streams).

## Test it

Send a message to the Number from another phone, or between two
[test numbers](https://docs.polymorfa.com/testing/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](https://docs.polymorfa.com/development/webhooks#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](https://docs.polymorfa.com/messaging/send#verify-delivery). |

## See also

- [Webhooks](https://docs.polymorfa.com/development/webhooks)
- [Event streams](https://docs.polymorfa.com/development/event-streams)
- [Conversation identity and message IDs](https://docs.polymorfa.com/messaging/ids)

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](https://docs.polymorfa.com/messaging/stickers).
