Skip to content
CommissionSight Docs

Webhooks

Register a webhook to be notified when jobs complete or fail.

Terminal window
curl -X POST https://api.commissionsight.com/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{ "url": "https://you.example.com/hooks/cs", "events": ["job.completed", "job.failed"] }'
# → { "id": "…", "secret": "whsec_…" }   ← the signing secret is shown ONCE

Payload

{ "jobId": "…", "status": "completed", "stats": { "green": 1100, "yellow": 80, "red": 18 },
  "_links": { "results": { "href": "…" }, "deltas": { "href": "…" } } }

Verifying the signature

Every delivery includes X-CommissionSight-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body using your webhook secret. Verify before trusting the payload:

import { createHmac, timingSafeEqual } from 'node:crypto';


export function verify(rawBody: string, header: string, secret: string): boolean {
  const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Failed deliveries are retried with backoff and recorded; persistently failing endpoints are logged.