Skip to main content

Register

PUT /webhook with your URL and the events you want (["*"] for everything, including types added later). One webhook per agency. The first call returns a signing secret once. To rotate, send a new secret (whsec_ plus 24 to 64 random bytes, base64): for 24 hours we sign with both. GET /webhook reads it, DELETE /webhook removes it, and POST /webhook/test sends a signed webhook.test event. The URL must be HTTPS on port 443. Put your own agency id in it: it tells you which secret to verify with before you parse anything. We don’t follow redirects, and we don’t have fixed IP addresses, so rely on the signature. Private addresses (localhost, 10.x, 192.168.x and the like) and URLs with a username or password are refused.

Delivery

  • Any 2xx counts as delivered. We time out after 10 seconds, so acknowledge first and process afterwards.
  • The first attempt is within a minute. Failures are retried after about 5 minutes, 30 minutes, then 2, 5, 10 and 10 hours: about 27 hours in all.
  • If your endpoint answers 410, we stop retrying and switch the webhook off. If every delivery fails for 5 days, we switch it off and email you and the agency. A new PUT /webhook switches it back on.
  • At least once: you may see an event twice. webhook-id is the same on every retry. Keep the ids you’ve processed for 48 hours and skip repeats. When you catch up with GET /events, skip ids you’ve already processed.
  • No ordering guarantee. Use the body’s timestamp if order matters.

Verify the signature

Events are signed to the open Standard Webhooks specification.
Verify against the raw body, before parsing. Reject a timestamp more than 5 minutes from your clock.
Check your code against the specification’s published test values. It must produce exactly this signature:

Catch up, or poll

GET /events?after=<last id you processed> returns the agency’s events from the last 30 days, oldest first, in the same envelope, delivered or not. Use it after an outage, or instead of a webhook altogether. Each page gives has_more (call again straight away) and next_after (pass it next time; absent only when there are no events yet and you sent no after). An after older than 30 days answers 410 cursor_expired: start again without it and reconcile.

The events

Every event has the same envelope. data depends on type, and each one is documented in the API reference. Every event about a person carries contact_id, Signal’s id for the person, and contact, their name, phone and email. note.added may not, and webhook.test never does. See Contacts.