Skip to main content

Usage webhooks

Prism can POST a signed event to your endpoint for every billed call your organization makes. Use it to reconcile spend, drive internal chargeback, or feed your own dashboards without polling the usage API. Set endpoints up yourself in the console under Team → Usage webhooks. Prism generates the signing secret and shows it once at creation.

What arrives

One POST per usage event, content-type: application/json:
cost_credits_minor is in minor units — 143 is ฿1.43. Headers:
This is the Standard Webhooks envelope, so an existing Standard Webhooks verifier works unchanged.

Verifying

The signed message is {webhook-id}.{webhook-timestamp}.{raw body}.
Sign the raw request body, before any JSON parsing. Re-serialising a parsed object changes key order and whitespace, and the signature will not match.

Responding

Return any 2xx as soon as you have stored the event. Do the work afterwards — a slow handler burns your retry budget. Anything else is treated as a failure and retried with exponential backoff (1 min, 2, 4, 8 … capped at 1 hour) until the attempt limit, after which the delivery is marked dead and shown in the console with the last error.

Idempotency

Retries mean the same event_id can arrive more than once. Treat event_id as the primary key on your side and ignore duplicates — do not add to a running total on every delivery.

Ordering

Deliveries are not ordered. A retried event can arrive after a newer one. Use occurred_at rather than arrival order when sequence matters.

Rotating the secret

The secret is shown once and stored encrypted; Prism cannot show it to you again. To rotate, add a second endpoint with the same URL, deploy a receiver that accepts either secret, then remove the old endpoint.