GUIDE

Webhooks

Webhooks let you connect the Decision Receipt API to the rest of your tooling without polling. Register an outbound webhook to be told the moment a receipt is created, and point the inbound GitHub webhook at the API to have pull requests evaluated automatically. This guide covers both directions and the one rule that ties them together: verify before you trust.

Outbound webhooks

An outbound webhook registers a receiver for receipt.created events. Once registered, every time a receipt is produced — by an explicit POST /v1/evaluate call or by the inbound GitHub flow below — the API delivers that event to your URL. That is what turns receipts into something you can act on in real time: post a verdict back to a pull request, drop a message into a chat channel, forward the record to a SIEM, or append it to your own ledger.

Register a receiver with POST /v1/webhooks/outbound, authenticated with your X-API-Key. A successful registration returns 201.

REQUEST

curl -s https://decrec.summitcognitive.ai/v1/webhooks/outbound \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_decrec_<your-key>" \
  -d '{
    "url": "https://hooks.example.com/decrec",
    "event": "receipt.created"
  }' | jq .

The delivery carries the receipt itself — the same receipt object you would get back from POST /v1/evaluate, with its receipt_id, admissibility, evidence, policy, attestations[], and chain. For the full anatomy of that object and what each section means, see the Decision Receipt concept page.

What a consumer should do on receipt

When your endpoint receives a receipt.created delivery, a robust consumer does three things before it acts.

1. Parse the receipt. Read the receipt object out of the request body. The fields you care about most are receipt.policy.verdict (the decision) and receipt.admissibility.status (whether the receipt itself is admissible).
2. Confirm integrity before acting. The transport delivered the receipt, but the transport is not the authority. Send the receipt to POST /v1/verify — or check its Ed25519 signature offline — to confirm it has not been altered and was genuinely signed by the issuing server. Act only when verification passes.
3. Branch on the verdict. Route the action on verdict: ALLOWED means the policy checks passed and you can proceed; BLOCKED means the action was refused and should be stopped; ESCALATED means it needs a human in the loop before anything continues.

A typical handler maps each verdict onto a side effect — comment ALLOWED on the PR and let the merge proceed, comment BLOCKED with the failing policy rules, or open a review request on ESCALATED. Because the verdict and its supporting evidence travel inside the receipt, your consumer never has to call back to reconstruct context.

Inbound GitHub webhook

The API can also sit on the receiving end. Point a GitHub webhook at POST /v1/webhook/github and the API will auto-evaluate pull requests as they change — producing a receipt for each without you writing any evaluation glue. This endpoint authenticates by signature: GitHub signs each delivery, the API checks that signature, and a bad or missing signature is rejected with 401.

The inbound and outbound webhooks compose naturally. GitHub fires the inbound webhook on a pull request, the API evaluates it and emits a receipt, and that receipt is then delivered to every registered outbound receiver as a receipt.created event. For the full setup — secret configuration, which pull-request events are handled, and how the evaluation maps onto policy — see the GitHub integration guide.

Verify before you trust

The transport that delivers a webhook is not what makes a receipt trustworthy. A delivery could be spoofed, replayed, or altered in flight, so a webhook consumer should verify the receipt's signature rather than trust the fact that it arrived. This is the whole reason receipts are independently verifiable: you do not have to believe the channel, because you can check the cryptography.

For exactly how to run that check, both online and offline, see Verifying receipts.