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 when an event occurs, like a storyboard moving to Approved.

See also: Webhooks in API and webhooks, an overview of what you can automate with Boords.

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. Webhooks are available on paid plans, and you'll need an Owner or Admin 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
• Your signing secret is shown once, when you create the endpoint, so copy it straight away
• Use Send test in the endpoint's menu to send a sample project.created event

Available events

Most events fire for changes made through the Boords API or an AI connection, such as Claude or ChatGPT. Changes made in the Boords web app send only these events:

• storyboard.updated, when anyone changes a storyboard's status, including a move between two of your team's statuses in the same category.
• script.updated, when anyone changes a script's status, including when the Boords Agent sets it.
• frame.created, when the Boords Agent adds frames to a storyboard.
• notification.created, for personal notification endpoints (see Personal notifications).

Comments, frame edits, changes to a script's text or name, and new projects, storyboards or scripts made in the web app don't send team webhooks. To keep track of those, read the team activity feed with the API (GET /v1/teams/{team_id}/events).

Boords can notify your endpoint about the following events:

Projects

Storyboards

Scripts

Frames

Comments

Personal notifications

notification.created fires for comments made in the app as well as through the API. It covers storyboard comments only, not script comments.

It belongs to you rather than your team. Any team member can register one for their own account with a POST /v1/webhook_endpoints request. It can't be set up in Settings, and an endpoint can't mix it with team events.

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 uses the same type, id and attributes as the matching API resource, so you can use the same parsing logic for both webhook payloads and API responses. It doesn't include the API's revision field, the previous values, or who made the change. To find out who changed a storyboard's or script's status, read the team activity feed.

Storyboard and script payloads carry two status fields. status is the status category: null for Draft, then in_progress, review_needed, changes_required or approved. custom_status is your team's own status, for example { "id": "<uuid>", "name": "Client review" }. A move between two statuses in the same category fires storyboard.updated or script.updated with status unchanged, so compare custom_status if you track your team's statuses. Editing your team's statuses in Team settings sends no webhooks, even when deleting a status moves items to its category's default.

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:

To verify a delivery:

1. Concatenate the timestamp, a period (.), and the raw request body: timestamp.raw_body
2. Compute an HMAC SHA256 hash of that string using your webhook signing secret
3. 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:

• Boords keeps trying a delivery until your endpoint accepts it or the retries run out
• 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 the delivery, waiting longer between each try. It makes 5 attempts in all, over about 6 minutes, and then stops. There's no delivery log or replay, so if your endpoint might be down for longer, use the API's updated_since filter to catch up.

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
• Check the timestamp. Boords doesn't enforce a time limit, so reject deliveries whose X-Boords-Timestamp is more than a few minutes old
• Filter what you need. storyboard.updated and script.updated fire for several kinds of change. Check status for the category, such as approved, or custom_status.id for one of your team's own statuses. A status keeps its id when your team renames it. The payload doesn't include the previous status, so store the last status you saw for each item and act only when it changes
• Monitor your endpoint. If deliveries consistently fail, check your server logs and ensure your endpoint is accessible