Webhooks

Webhooks push an event to your own URL the moment something happens in your workspace, so you never have to poll for changes. Add an endpoint under Developer > Webhooks, choose the events you want or pick All events, and each matching change sends a signed POST.

Every event WorkBOS can send is listed below. It is the same list WorkBOS itself holds, and a build check fails when the platform starts sending a type this table does not name, so it cannot quietly fall behind again: it listed eight events while nineteen were being sent.

• X-WorkBOS-Event names the event that fired, using the same names as the table above.
• X-WorkBOS-Signature-V1 is what to verify: t=<unix seconds>,v1=<lowercase hex>. Check t is within five minutes of your clock, then recompute HMAC-SHA256 over the exact string "<t>.<raw body>" with your endpoint secret and compare it to the v1 half. Because the timestamp is signed, a delivery somebody captured yesterday stops verifying.
• X-WorkBOS-Signature is the form integrations written before this used, and is still sent, unchanged: "sha256=" followed by the HMAC-SHA256 of the raw body alone. It verifies the same bytes for ever, so treat it as a fallback while you move to the timestamped one. An endpoint with no secret set is never delivered to, so neither header is ever empty.
• X-WorkBOS-Timestamp repeats the t value for readability. X-WorkBOS-Delivery repeats the delivery id, which is also inside the body as workbos_delivery_id. Read the body one, because the body is signed and headers are not. A delivery that fails is retried automatically with backoff, up to six attempts, so the same id can arrive more than once: treat it as an idempotency key.

const crypto = require('crypto');

function isValidWorkBOSSignature(rawBody, headerValue, endpointSecret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', endpointSecret).update(rawBody).digest('hex');
  const a = Buffer.from(headerValue || '');
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the unparsed request body, for example from express.raw().
app.post('/webhooks/workbos', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-WorkBOS-Signature') || '';
  if (!isValidWorkBOSSignature(req.body, header, process.env.WORKBOS_ENDPOINT_SECRET)) {
    return res.status(401).send('invalid signature');
  }
  res.status(200).send('ok');
});