Skip to main content
Instead of polling, let Five API call you. When a task reaches a terminal status, Five API sends a signed POST to your endpoint with the full task object.

Set up an endpoint

You can send events to two places:
  • A default endpoint for the account. Set it on the Webhooks page of the console. It receives the events of every task that has no webhook_url of its own.
  • A per-task endpoint. Pass webhook_url when you create the task. It overrides the default endpoint for that task.
Endpoints must use https and be reachable from the public internet. On the Webhooks page you can also copy your signing secret, rotate it, send a signed test event to your endpoint, and see every delivery attempt.

Events

Each event carries the full task object in data, including your metadata:
The request carries these headers:

Verify the signature

Five API signs every event with your account’s signing secret, following the Standard Webhooks specification. Always verify the signature before you act on an event.
  1. Take the raw request body exactly as received, before any JSON parsing.
  2. Build the signed content: {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Decode the part of your secret after the whsec_ prefix from base64. That is the HMAC key.
  4. Compute HMAC-SHA256 of the signed content and encode it in base64.
  5. Compare it, in constant time, with each v1, value of webhook-signature. One match is enough.
  6. Reject events whose webhook-timestamp is more than 5 minutes away from your clock.
The open-source Standard Webhooks libraries for Python, JavaScript, Go, Java, PHP, Ruby and more verify this format out of the box. Pass them your whsec_... secret and the three headers.

Test your verifier

Feed these exact values to your verifier. It must accept the signature, and reject it as soon as one byte of the body, the id or the timestamp changes. Disable the timestamp check for this test, because the timestamp is fixed. Raw body: 877 bytes, one line, no trailing newline.

Handle events

Answer with any 2xx within 10 seconds, then do the work. A slow handler times out and the event is sent again.

Delivery and retries

Best practices

  • Verify every event with the signing secret, over the raw body.
  • De-duplicate on webhook-id. A retry delivers the same event again.
  • Acknowledge fast and process asynchronously.
  • Carry your own ids in metadata, so a handler can route an event without a lookup.
  • Treat the task as the source of truth. If an event seems late or missing, call GET /v1/tasks/{task_id}.
  • Rotate the secret from the console if it leaks. During the rotation the signature header carries a value for each secret, so a verifier that accepts any matching v1, value keeps working.