Skip to content
Neattrim

Webhooks

View as Markdown · Open in Claude Desktop

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.

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

const event = await verifyWebhook(rawBody, headers, process.env.NEATTRIM_WEBHOOK_SECRET);
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.

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
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.