Bila← Docs

Handling webhooks

Bila sends every state change to your registered endpoints — signed, retried, and idempotent. Implement the verification correctly and you can trust the signal.

Verify the signature

Every delivery carries a Bila-Signature header in the form t=<timestamp>,v1=<hex>. The v1 signature is HMAC-SHA256 of t.body using your endpoint's signing secret.

import crypto from 'node:crypto';
function verify(body, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  if (Math.abs(Date.now()/1000 - Number(t)) > 300) return false; // 5-min replay window
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Reply 2xx fast

Bila considers any 2xx a successful delivery. Anything else triggers retries on this schedule: 1m, 5m, 30m, 2h, 6h, 12h, 24h, 36h, 48h (9 attempts over ~72h). After the 9th failure the delivery moves to exhausted and you'll get an email.

Make your handler idempotent

You will receive every event at least once. Bila guarantees each event.id uniquely identifies a state change — store the ids you've processed and short-circuit on repeats.

Dead-letter recovery

Resend any exhausted delivery from /dashboard/webhooks. Bila keeps the full request payload for 30 days.