# Webhooks

URL: https://neattrim.com/docs/webhooks

Webhook events, signature checks and replays for the Neattrim API.

A webhook tells your server that something finished, so you do not need to poll. Register an endpoint with `POST /v1/webhook-endpoints`. The signing secret is shown once.

## Events

| Event | When it is sent |
| --- | --- |
| `job.completed` | A job finished and its output files are ready. |
| `job.failed` | A job failed. You are not charged. |
| `job.cancelled` | A job was cancelled. |
| `batch.completed` | Every item of a batch has ended. |
| `balance.low` | An allowance is running low. |
| `balance.exhausted` | An allowance is used up. |
| `library.item_expiring` | A file in the library is about to expire. |

Send a signed sample event with `POST /v1/webhook-endpoints/<id>/test`. `GET /v1/webhook-endpoints/<id>/deliveries` lists deliveries, and a delivery can be replayed. A replay sends the same `webhook-id` and the same bytes.

## Check the signature

Webhooks follow the Standard Webhooks layout. Each request has three headers: `webhook-id`, `webhook-timestamp` and `webhook-signature`. The signed text is `<id>.<timestamp>.<raw body>`. The signature is `v1,` followed by the base64 HMAC-SHA256 of that text.

The signing secret looks like `whsec_` followed by base64. The key is the bytes you get when you decode the base64 part, not the secret as text. During a secret rotation the `webhook-signature` header holds two signatures separated by a space: accept the request when any one of them matches. Check the signature against the raw bytes of the body, not parsed JSON, and reject a timestamp more than five minutes from now. Deliveries are sent at least once, so ignore an event whose `webhook-id` you have already handled.

The SDKs include `verifyWebhook` (TypeScript) and `verify_webhook` (Python). They are not on npm or PyPI yet (they arrive with the first client release), so until then use the check without an SDK further down.

```ts
import { verifyWebhook } from "@neattrim/sdk";

const event = await verifyWebhook(rawBody, headers, process.env.NEATTRIM_WEBHOOK_SECRET);
```

```python
from neattrim import verify_webhook

event = verify_webhook(raw_body_bytes, headers, secret)
```

Without an SDK, do the check yourself with your language's HMAC and a constant-time comparison.

```bash
KEY_HEX=$(printf '%s' "${SECRET#whsec_}" | base64 -d | xxd -p -c 256)
printf '%s.%s.%s' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP" "$RAW_BODY" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$KEY_HEX" -binary | base64
```

```go
key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
if err != nil {
	return false
}
mac := hmac.New(sha256.New, key)
mac.Write([]byte(id + "." + timestamp + "." + string(body)))
expected := mac.Sum(nil)

ok := false
for _, candidate := range strings.Split(signature, " ") {
	version, value, found := strings.Cut(candidate, ",")
	if !found || version != "v1" {
		continue
	}
	got, err := base64.StdEncoding.DecodeString(value)
	if err == nil && hmac.Equal(got, expected) {
		ok = true
	}
}
return ok
```

## Delivery

Answer with any `2xx` status within a few seconds. A failed delivery is retried. An endpoint that keeps failing is disabled and we email you; enable it again with `POST /v1/webhook-endpoints/<id>/enable`.
