> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Register native or Meta-format webhooks, verify signatures, configure retries, and consume supported events.

Register webhooks with `POST /api/webhooks`. An empty `events` array subscribes
to every event; an optional `session` restricts delivery to one session.

## Manage webhooks in the Console

Open team **Settings → Webhooks** to list, add, edit, enable, disable, or delete
webhook endpoints. Each endpoint supports a public URL, an optional event
selection, native or Meta-compatible format, an optional signing secret, and a
retry policy.

Retry attempts range from `0` to `10`, and retry delay ranges from `0` to
`3600` seconds. Policies are `constant`, `linear`, or `exponential`. Leaving
the event selection empty subscribes the endpoint to every supported event.
The Console never displays a stored signing secret; enter a replacement to
rotate it or explicitly clear it.

```bash theme={null}
curl -X POST "https://api.polymorfa.com/api/webhooks" \
  -H "Authorization: Bearer $TITAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/polymorfa/webhook",
    "events": ["message.received", "message.ack", "session.status"],
    "hmacKey": "replace-with-a-random-secret",
    "format": "native",
    "retries": { "attempts": 3, "delaySeconds": 5, "policy": "exponential" }
  }'
```

## Delivery formats

| Format             | Body                                       | Signature header                    |
| ------------------ | ------------------------------------------ | ----------------------------------- |
| `native` (default) | Polymorfa event envelope                   | `X-Webhook-Signature: <hex>`        |
| `meta`             | Meta `object/entry/changes/value` envelope | `X-Hub-Signature-256: sha256=<hex>` |

Both signatures are HMAC-SHA256 over the exact raw HTTP body using `hmacKey`.
Compare in constant time before parsing JSON. The signature is absent when no
key is configured.

## Retry configuration

`retries.attempts`, `retries.delaySeconds`, and `retries.policy` are stored per
webhook. Policies are `constant`, `linear`, or `exponential`; exponential delay
is capped at five minutes. The default is three attempts, five seconds, and
exponential backoff.

## Current event catalog

The Messaging API OpenAPI document publishes all payload types through `x-webhooks`.
There are 31 current events:

```text theme={null}
message.received   message.sent       message.ack
message.delete     message.edited     message.reaction
message.revoked    message.update     message.vote

session.qr         session.connected  session.status
session.logged_out

chat.archive       chat.clear         chat.delete
chat.mute          chat.read

contact.update     blocklist.update   group.update
group.participant  newsletter.update  presence.update
labels.update      history.sync

call.received      call.accepted      call.rejected
call.missed        command.result
```

Use the schema associated with each `x-webhooks` operation for the exact
payload. Common message fields include typed `JIDRef`, media metadata, reaction,
poll, edit, and unavailable-state fields; session, group, contact, call, and
command events each have their own named component.

## Receiver rules

* Return any `2xx` only after the event is durably accepted.
* Deduplicate with the event identifier from the delivered envelope.
* Expect retries and possible cross-webhook reordering.
* Do not log raw bodies or signature secrets; message payloads may contain
  customer content.
* Use `format: "meta"` when migrating an existing Meta webhook consumer and
  `native` for the complete Polymorfa event catalog.

The generated Messaging API endpoint pages document webhook CRUD request and
response types; its `x-webhooks` section documents event bodies.