Skip to content
BredboxHelp

Use webhooks

Webhooks are for Pro users who want Bredbox to notify another service the moment something happens in their account — a save created, an import finished, a highlight added.

Before you start

Section titled “Before you start”

You need:

  1. A Pro plan.
  2. A public HTTPS endpoint that can receive POST requests.
  3. A place to store the webhook signing secret.

Create a webhook

Section titled “Create a webhook”
  1. Open Settings → Webhooks.
  2. Create a new webhook.
  3. Give it a clear name.
  4. Enter the destination URL.
  5. Choose whether to subscribe to all events or specific event types.
  6. Save the webhook and store the signing secret.

Choose events deliberately

Section titled “Choose events deliberately”

Events are named area.action. The ones most integrations start with:

  • save.created, save.updated, save.trashed, save.restored, save.deleted
  • save.metadata.completed — fires when Bredbox finishes processing a save, useful when you want the enriched record
  • save.tags.updated, save.highlight.created
  • import.completed, export.completed
  • Collection, token, and authorization events for account-level auditing

The webhook creation screen lists the full catalog with descriptions, as does the API reference.

If your integration only needs a few events, subscribe to those instead of all events — your endpoint stays quieter and easier to monitor. Use all events when you are building a general sync process and expect to handle new event types over time.

Verify webhook payloads

Section titled “Verify webhook payloads”

Treat webhook requests as untrusted until your endpoint verifies the signature. Bredbox signs deliveries following the Standard Webhooks convention:

  • Each delivery carries webhook-id, webhook-timestamp, and webhook-signature headers.
  • The signature is an HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with your signing secret, sent as v1,<base64>.
  • Any Standard Webhooks verification library can check it — or a few lines of your own HMAC code.

Good practice:

  • Verify every incoming payload before acting on it.
  • Reject deliveries whose timestamp is too old, to block replays.
  • Return a successful HTTP response only after your endpoint accepts the event.
  • Log failures without exposing secrets.

Disable or rotate a webhook

Section titled “Disable or rotate a webhook”

Open Settings → Webhooks when you need to:

  • Temporarily stop deliveries
  • Change event subscriptions
  • Rotate a signing secret
  • Review recent delivery history
  • Delete an integration you no longer use
Section titled “Related guides”