Webhook best practices

Outbound webhooks let your systems react when Boson marks a notification sent or failed. Treat them like any other event stream: verify, acknowledge quickly, and process idempotently.

Acknowledge first

Return 2xx as soon as you have accepted the payload. Do heavy work in a queue. Providers retry on timeouts; slow handlers create duplicates.

Make handlers idempotent

Use the notification id (or a delivery id if present) as a unique key. If the same webhook arrives twice, the second call should be a no-op.

async function onWebhook(body: { id: string; status: string }) {
  const inserted = await db.insertIgnore("webhook_receipts", { id: body.id });
  if (!inserted) return;
  await enqueue(body);
}

Verify the source

Only accept requests from endpoints you registered, and check any signing headers Boson documents for your workspace. Never trust a public URL that anyone can POST to.

Prefer the activity log for truth

Webhooks are a push hint. If your consumer is down, catch up from the console activity log or inbox APIs instead of assuming the stream was complete.

When you are ready to configure endpoints, open the console and add a webhook for the statuses you care about.