Skip to main content

Webhooks & events

The push counterpart to polling. The platform calls your HTTPS endpoint when something happens.

What you'll learn​

  • How to register a webhook
  • The delivery contract (retries, signing, idempotency)
  • Available event types

Register a webhook​

From the web app: Settings → Webhooks → New webhook.

  • URL — your HTTPS endpoint (no HTTP)
  • Events — pick what you want notified about
  • Secret — used to sign each delivery

Programmatically:

mutation {
createWebhook(input: {
url: "https://your-app.example.com/burdenoff-webhook"
eventTypes: ["file.uploaded", "invoice.paid"]
secret: "..."
}) { id }
}

Delivery contract​

PropertyValue
MethodPOST
Content-Typeapplication/json
Signature headerX-Burdenoff-Signature: t=<unix-time>, v1=<hex-hmac-sha256>
RetriesExponential backoff, max 6 attempts over ~24h
Success2xx response within 10s
Failure → DLQAfter 6 attempts, event moves to your webhook's DLQ

The signed string is <unix-time>.<raw-body>. HMAC-SHA256 with your shared secret. Verify it before processing.

import { createHmac } from 'crypto';

function verify(req): boolean {
const sig = req.headers['x-burdenoff-signature'];
const [tPart, v1Part] = sig.split(', ');
const t = tPart.split('=')[1];
const v1 = v1Part.split('=')[1];
const expected = createHmac('sha256', SECRET).update(`${t}.${req.rawBody}`).digest('hex');
return expected === v1;
}

Idempotency​

Every delivery carries X-Burdenoff-Delivery-Id: <uuid>. Store seen IDs and ignore repeats — retries will reuse the same delivery ID.

Event types​

A non-exhaustive list:

EventPayload
workspace.member.addeduserId, workspaceId, role
file.uploadedfileId, workspaceId, uploadedBy, size, mimeType
conversation.message.sentmessageId, conversationId, authorId
invoice.paidinvoiceId, amount, currency
rbac.role.changeduserId, oldRoles, newRoles
scheduler.job.failedjobId, attemptNumber, error

Full list in the GraphQL schema under WebhookEventType enum.

Next steps​

  • To register webhooks via the UI, look for Settings → Webhooks in the web app.
  • Eventing concept — for internal service module-to-service module events (use SDK, not webhooks)