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

# Webhooks

> Register, verify, retry, catch up.

## 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](https://www.standardwebhooks.com) specification.

```text theme={null}
webhook-id:        evt_9c1e4b7a52d04c1f
webhook-timestamp: 1789727475            (unix seconds, this delivery attempt)
webhook-signature: v1,<base64 signature> (several, space-separated, during a rotation)

signed content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed content ) )
key            = base64-decode of the secret, without its "whsec_" prefix
```

Verify against the raw body, before parsing. Reject a timestamp more than 5 minutes from your clock.

```php theme={null}
<?php
// PHP 7 and later, no library needed. $secret: look it up from the agency id in your URL.
$id  = isset($_SERVER['HTTP_WEBHOOK_ID'])        ? $_SERVER['HTTP_WEBHOOK_ID']        : '';
$ts  = isset($_SERVER['HTTP_WEBHOOK_TIMESTAMP']) ? $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] : '';
$sig = isset($_SERVER['HTTP_WEBHOOK_SIGNATURE']) ? $_SERVER['HTTP_WEBHOOK_SIGNATURE'] : '';
$raw = file_get_contents('php://input');

if ($id === '' || $ts === '' || $sig === '')  { http_response_code(400); exit; }
if (abs(time() - (int)$ts) > 300)             { http_response_code(400); exit; }

$key = base64_decode(substr($secret, strlen('whsec_')), true);
if ($key === false)                           { http_response_code(500); exit; }

$expected = 'v1,' . base64_encode(hash_hmac('sha256', $id . '.' . $ts . '.' . $raw, $key, true));

$valid = false;
foreach (explode(' ', $sig) as $candidate) {
    if (hash_equals($expected, $candidate)) { $valid = true; break; }
}
if (!$valid) { http_response_code(401); exit; }

// Verified. If $id was processed already, return 200 and stop.
// Otherwise store $id and $raw (a queue table is fine), return 200, and process them from a scheduled job.
```

Check your code against the specification's published test values. It must produce exactly this signature:

```text theme={null}
secret     whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw   (public test value: never use it for real)
id         msg_p5jXN8AQM9LWM0D4loKWxJek
timestamp  1614265330
body       {"test": 2432232314}
signature  v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
```

## 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](https://docs.signalproptech.com/guides/contacts.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.