Webhooks

A webhook sends your server a request every time a run changes state. It is the simplest way to keep another system in step with Kestrel.

Add an endpoint

Under Settings, Webhooks, add a URL and choose the events you want. Kestrel sends a test event straight away so you can check that it arrives.

Events

• run.resolved when a ticket is closed.
• run.waiting when Kestrel asks a person.
• run.handed_over when a ticket goes to your team.
• rule.changed when someone edits a rule.

What a request looks like

1{2  "event": "run.waiting",3  "run": "run_48214",4  "ticket": "81226",5  "category": "refunds",6  "asked": { "amount": 34000, "currency": "usd", "over_limit_by": 14000 }7}

Check the signature

Every request carries a Kestrel-Signature header. Compare it with a hash of the body made with your endpoint's secret, and ignore any request that does not match.

1import { createHmac, timingSafeEqual } from 'node:crypto'2 3export function isFromKestrel(body: string, signature: string, secret: string) {4  const expected = createHmac('sha256', secret).update(body).digest('hex')5  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature))6}

Retries

Answer with a 2xx status within ten seconds. If you do not, Kestrel tries again six times over a day, waiting longer each time. Each event has an id, so you can ignore one you have already handled.