Webhooks
Rather than polling GET …/cards/{ref}, set a webhook on the token and
the platform calls your application: a card.status whenever a card’s
phase changes, and a
feedback.outcome when feedback is accepted or refused. Every delivery is
signed with a secret only you and the platform hold, retried when your end
is down, and listed under the token with what your end answered.
Set one
Section titled “Set one”Your settings → API tokens, under the token: a URL, Tell it about — Cards this token filed (the default) or Every card in its projects — and Save webhook. A dialog shows the signing secret once; use Copy secret to put it in your application’s configuration beside the token, then Close.
Then press Send a test. The platform POSTs a ping — the envelope with
no subject — so you can check your signature verification before anything
real arrives. It appears under Last deliveries with what your end answered.
One webhook per token. Changing the URL or the scope keeps the secret; Rotate secret asks first, then issues a new one, shown once in the same dialog, and the old one stops verifying the moment it does. Remove deletes the webhook with its deliveries.
The URL
Section titled “The URL”The platform is calling out from inside a deployment, so the URL is held to
a few rules, each named in the 400 when broken:
https, orhttptolocalhostfor a receiver on the machine cawdev itself runs on.- No credentials in it.
- Its host may not resolve to a loopback, private, link-local, carrier-grade NAT or multicast address — the platform must not be pointed at its own network.
- Redirects are never followed.
The request
Section titled “The request”Every delivery is a POST with Content-Type: application/json, User-Agent: cawdev-webhook, and four headers:
| Header | Carries |
|---|---|
X-Cawdev-Event |
card.status, feedback.outcome or ping |
X-Cawdev-Delivery |
The delivery’s id — also delivery in the body |
X-Cawdev-Sequence |
A counter per webhook, increasing — also sequence in the body. Two deliveries that arrive out of order are told apart by it |
X-Cawdev-Signature |
sha256=<hex>, below |
The body is an envelope, and for the two real events a subject beside it:
{ "event": "card.status", "delivery": "9c4a…", "sequence": 42, "sentAt": "2026-09-21T10:02:43Z", "token": { "label": "support-tool" }, "project": { "slug": "my-project", "name": "My project" }, "card": { "ref": "R12", "kind": "ROADMAP", "title": "Export to CSV", "status": "IN_DEVELOPMENT", "phase": "CODING", "work": { "branch": "r12-export-to-csv", "status": "CODING", "prUrl": null, "note": null, "signedOff": false }, "run": { "id": "2b7e…", "profile": "CODE", "state": "RUNNING", "startedAt": "2026-09-21T10:02:41Z", "finishedAt": null }, "path": "/projects/my-project/roadmap/R12", "url": "https://app.cawdev.com/projects/my-project/roadmap/R12", "updatedAt": "2026-09-21T10:02:41Z" }}event |
Carries | When |
|---|---|---|
card.status |
project and card — the same shape GET …/cards/{ref} answers |
A card in the webhook’s reach changed phase |
feedback.outcome |
project and feedback — the same shape GET …/feedback/{id} answers |
A person accepted or refused feedback in the webhook’s reach |
ping |
The envelope alone | Send a test |
Reach is the scope you chose: Cards this token filed means the cards and feedback this token filed itself; Every card in its projects means every card on every project the token holds.
Verify the signature
Section titled “Verify the signature”X-Cawdev-Signature is sha256= followed by the lower-case hex of
HMAC-SHA256 over the raw request body bytes, with the secret as the key.
Compute it over the bytes you received, before parsing them, and compare
with a constant-time equality. Reject anything that does not verify before
you read a field of it. A complete receiver in Node, no dependencies:
const crypto = require('node:crypto');const http = require('node:http');
http.createServer((req, res) => { const chunks = []; req.on('data', (c) => chunks.push(c)); req.on('end', () => { const raw = Buffer.concat(chunks); const expected = 'sha256=' + crypto.createHmac('sha256', process.env.SECRET).update(raw).digest('hex'); const given = req.headers['x-cawdev-signature'] ?? ''; const ok = expected.length === given.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given)); if (!ok) { res.writeHead(401); return res.end(); } const event = JSON.parse(raw); // { event, sequence, project, card: { ref, phase, … } } console.log(req.headers['x-cawdev-event'], event.card?.ref, event.card?.phase); res.writeHead(200); res.end(); });}).listen(8787);Run it with SECRET=whsec_… node receiver.js, set the webhook to
http://localhost:8787/ on a local instance, and press Send a test.
Answering, retries, and giving up
Section titled “Answering, retries, and giving up”Answer 2xx within ten seconds. What happens otherwise:
| Your end answers | The platform |
|---|---|
2xx |
Delivered |
5xx, 408, 429, a timeout, a refused connection |
Retries after 30 s, 1 min, 3 min and 10 min — five attempts in all, then it gave up |
Any other 4xx |
Taken as “will keep saying no” — the delivery fails at once |
Ten undelivered deliveries in a row disable the webhook; the token’s card
says so, and Save re-enables it. Two changes to one card inside one backoff
reach you as the later one, and sequence tells two deliveries apart when
they arrive out of order.
Last deliveries
Section titled “Last deliveries”Under the token, the last fifty deliveries newest first: the event, its sequence, how many attempts, when it was delivered or failed, what your end answered (the status and the first 200 characters of the body), and why it is retrying or gave up. Never the body that was sent and never the secret. It is where “did it send, and what did my server say” is answered without adding logging to your receiver.