Developers/Webhooks

Webhooks

Webhooks let you receive automatic notifications when something changes in your Boords workspace. Instead of polling the API to check for updates, Boords sends an HTTP request to your server whenever an event occurs — like a storyboard being created or a frame being updated.

Webhooks are currently in Beta alongside the Boords API. The core functionality is stable, but some details may change as we refine the experience.

Setting up webhooks

You can create and manage webhook endpoints in Settings → Team → API, or via the API itself. You'll need an Admin or Manager role.

A few things to know:

Webhook URLs must use HTTPS
Each team can have up to 10 webhook endpoints
You can choose which events each endpoint receives

Available events

Boords can notify your endpoint about the following events:

Projects

Event	Fires when
`project.created`	A new project is created
`project.updated`	A project's name or details change
`project.archived`	A project is archived

Storyboards

Event	Fires when
`storyboard.created`	A new storyboard is created (including duplicates and new versions)
`storyboard.updated`	A storyboard's name, status, or details change
`storyboard.archived`	A storyboard is archived

Frames

Event	Fires when
`frame.created`	A new frame is added to a storyboard
`frame.updated`	A frame's content, image, or status changes
`frame.deleted`	A frame is removed from a storyboard

Comments

Event	Fires when
`comment.created`	A new comment is added to a frame
`comment.updated`	A comment's text or status changes (e.g. marked as completed)
`comment.deleted`	A comment is removed

Payload format

Each webhook delivery includes a JSON payload with the event details:

{
  "id": "evt_123",
  "event": "frame.updated",
  "occurred_at": "2026-01-25T15:22:41Z",
  "data": {
    "type": "frame",
    "id": 12345,
    "attributes": {
      "storyboard_id": "s9bx1z",
      "reference": "INT. OFFICE - DAY"
    }
  }
}

The data object follows the same format as the corresponding API resource, so you can use the same parsing logic for both webhook payloads and API responses.

Verifying webhook signatures

Every webhook delivery includes a cryptographic signature so you can verify it genuinely came from Boords. This prevents attackers from sending fake events to your endpoint.

Each request includes two headers:

Header	Contains
`X-Boords-Signature`	HMAC SHA256 signature
`X-Boords-Timestamp`	Unix timestamp of when the event was sent

To verify a delivery:

Concatenate the timestamp, a period (.), and the raw request body: timestamp.raw_body
Compute an HMAC SHA256 hash of that string using your webhook signing secret
Compare your computed signature with the X-Boords-Signature header

If the signatures match, the request is authentic. We recommend always verifying signatures in production, though it's not strictly required to receive events.

Delivery and retries

Boords uses at-least-once delivery, which means:

Every event is guaranteed to be delivered at least once
In rare cases, you may receive the same event more than once
Design your webhook handler to be idempotent — use the id field to detect and skip duplicate events

If your endpoint is unavailable or returns an error (any non-2xx status code), Boords retries delivery with exponential backoff. This gives your service time to recover without being overwhelmed by retries.

Tips for reliable webhook handling

Respond quickly — return a 200 status code as soon as you receive the event, then process it asynchronously
Handle duplicates — track event IDs to avoid processing the same event twice
Monitor your endpoint — if deliveries consistently fail, check your server logs and ensure your endpoint is accessible