> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/getting-started/webhooks.md).

# Webhooks

Webhooks push changes to you instead of you polling for them, and deliveries do not count against your API quota. Manage endpoints under `/v2/webhook-endpoints`.

#### Event types

`GET /v2/webhook-event-types` returns the live catalog and needs no authentication. **Treat it as the source of truth** — subscribe from it rather than from a hardcoded list.

The `events` array on an endpoint is not validated against the catalog. A misspelled type is accepted, stored, and never fires, with no error at creation time and nothing in the delivery log to inspect, because no delivery is ever attempted. Omitting `events` subscribes to everything.

#### Verifying the signature

Every delivery carries a `Spiffy-Signature` header:

```
Spiffy-Signature: t=1755043200,v1=3f8a...c4
```

* `t` is the Unix timestamp at signing.
* `v1` is a hex-encoded HMAC-SHA256, using your endpoint's signing secret as the key, over the exact string `{t}.{raw request body}`.

Sign the **raw body as received**. Parsing the JSON and re-serializing it will change key order or spacing and the signature will not match.

```js
const crypto = require('crypto');

function verify(rawBody, header, secret) {
    const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
    const expected = crypto.createHmac('sha256', secret)
        .update(parts.t + '.' + rawBody)
        .digest('hex');
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
```

Compare with a constant-time function, and reject deliveries whose `t` is outside a tolerance you choose, so an intercepted payload cannot be replayed later. The signing secret is returned when you create an endpoint, and again from `POST /v2/webhook-endpoints/{id}/rotate-secret`.

#### Delivery

Delivery is **at-least-once and unordered**. The same event will eventually arrive twice, and a later state change can arrive before an earlier one. Deduplicate on the envelope `id`, and compare the object's own timestamps before writing rather than assuming the newest delivery is the newest truth.

A delivery succeeds on any 2xx within 10 seconds. Respond first and do your work afterward — once you return 2xx the event is considered delivered and will not be sent again.

Failures retry 7 times over roughly 34 hours: immediately, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. An endpoint that accumulates 50 consecutive failures is disabled automatically and its owners are emailed; any success resets the counter.

Events are only queued for endpoints that were active when they fired, so anything that happened while an endpoint was down, disabled or unsubscribed cannot be backfilled. Pair webhooks with a low-frequency `filter[updated_at.gte]` sweep to close that gap.

Endpoint URLs must be HTTPS and publicly resolvable; hostnames resolving to private or loopback addresses are refused at delivery time.
