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
| Property | Value |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Signature header | X-Burdenoff-Signature: t=<unix-time>, v1=<hex-hmac-sha256> |
| Retries | Exponential backoff, max 6 attempts over ~24h |
| Success | 2xx response within 10s |
| Failure → DLQ | After 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:
| Event | Payload |
|---|---|
workspace.member.added | userId, workspaceId, role |
file.uploaded | fileId, workspaceId, uploadedBy, size, mimeType |
conversation.message.sent | messageId, conversationId, authorId |
invoice.paid | invoiceId, amount, currency |
rbac.role.changed | userId, oldRoles, newRoles |
scheduler.job.failed | jobId, 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)