Integrate webhooks

Webhooks push events to your own HTTPS endpoint instead of you polling for changes. Everything here needs the webhooks:manage scope — there's no separate read-only scope for webhooks, since a delivery record already carries your endpoint's URL and response data.

1. Register an endpoint

curl -X POST https://us.api.brault.app/v1/webhooks \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-bbbb-4c1a-9c1e-webhook-create" \
  -d '{
    "url": "https://example.com/hooks/brault",
    "name": "Production sync",
    "events": ["file.created", "file.deleted", "board.file.added"]
  }'

{
  "object": "webhook",
  "id": "<webhook_id>",
  "url": "https://example.com/hooks/brault",
  "name": "Production sync",
  "events": ["file.created", "file.deleted", "board.file.added"],
  "status": "active",
  "disabled_reason": null,
  "secret": "whsec_…",
  "secret_last4": "a1b2",
  "secret_rolled_at": null,
  "consecutive_failures": 0,
  "last_delivery_at": null,
  "last_success_at": null,
  "created_at": "2026-09-06T10:00:00.000Z",
  "updated_at": "2026-09-06T10:00:00.000Z",
  "created_by_id": "<user_id>"
}

secret is only ever in this response and in the response of POST …/roll-secret. Store it immediately — every other read of this endpoint returns secret: null and only secret_last4 for display. events accepts either a list of catalogue tokens or the single element "*" for everything, including events a future version of the catalogue adds. The endpoint URL must be https://, on port 443 (or an explicit 8443), and must resolve to a public address — see the Webhooks reference for the full validation rules.

Your receiver only needs to answer 2xx quickly. Verifying the payload is genuinely from Brault, and the full event catalogue, are covered on the Webhooks page — read that before wiring up production traffic.

2. Send a test delivery

curl -X POST https://us.api.brault.app/v1/webhooks/<webhook_id>/test \
  -H "Authorization: Bearer $BRAULT_API_KEY"

This delivers a synthetic webhook.test event to your endpoint right away — one attempt, no retry, and it works even on a paused or disabled endpoint. It never touches the endpoint's failure counters, so testing can't accidentally trip auto-disable.

3. What to expect once it's live

• At-least-once, no ordering guarantee. Design for idempotent handling on your side — every event has a stable id you can deduplicate on.
• Six attempts per delivery, roughly 15s, 1min, 5min, 30min and 2h apart (with jitter) after the first — about 2h36m of retry horizon for a receiver that's briefly down.
• Auto-disable kicks in after 100 consecutive failed deliveries, or 24 hours without a single success while failures continue. A PATCH back to "status": "active" clears the counters and resumes delivery — nothing that happened while disabled or paused is replayed.
• Events caused by your own key's requests are delivered too — unlike in-app notifications, which skip the actor's own actions.

See Webhooks for the full event catalogue and the signature verification snippets, and the Webhooks reference for every endpoint and delivery-record field.