Webhooks
A webhook lets n8n, Zapier, Make or a server of your own hear from Kadmo instead of asking: you subscribe a URL through the API, and Kadmo sends a signed POST to it when a job finishes, when a job needs a person and when a task is done. It is the trigger side of an automation; the API reference is the action side.
These are outgoing webhooks: Kadmo calls your URL. The webhooks of the tracker cards and of Settings → Logs → Webhooks are incoming: Jira, Linear or GitHub call Kadmo (Per-account webhooks).
Subscribe
A subscription is a URL and the events it takes, made with an API token:
curl https://app.kadmo.ai/api/v1/webhooks \
-H "Authorization: Bearer $KADMO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "url": "https://hooks.example.com/kadmo", "events": ["job.finished", "job.needs_input"] }'{
"id": 12,
"url": "https://hooks.example.com/kadmo",
"events": ["job.finished", "job.needs_input"],
"workspace": null,
"status": "active",
"disabled_reason": null,
"created_by": { "id": 4, "name": "Ada" },
"created_at": "2026-11-13T09:00:00.000Z",
"last_delivery_at": null,
"secret": "kadmo_whsec_…"
}| Field | What it takes |
|---|---|
url | An https address, at most 2,000 characters, with no user name, password or #fragment. Every address its host resolves to must be public: a private, loopback or link-local address, such as localhost or 169.254.169.254, is refused. |
events | At least one of job.finished, job.needs_input and task.done. |
workspace | Optional. A workspace's slug (GET /workspaces): the subscription then takes only that workspace's events. Unset, it takes every workspace's. |
The answer is 201 with the subscription and its secret, which signs every delivery. The secret is shown this once: keep it where the receiver reads it. With an Idempotency-Key, a retry of the same call answers the same subscription and secret again.
| Refused with | When |
|---|---|
422 invalid_webhook_url | The URL breaks one of the rules above; error says which. A host that does not resolve and one that resolves to a private address get the same sentence. |
503 webhook_check_unavailable | The host could not be looked up just now. Retry after Retry-After. |
404 workspace_not_found, 409 workspace_archived | The workspace is not the account's, or it is archived. |
409 webhook_limit_reached | You hold 100 subscriptions already. |
402 trial_expired | The trial has ended. Deleting still works. |
List and delete
GET /api/v1/webhooks lists your subscriptions, newest first, never with their secrets. DELETE /api/v1/webhooks/{id} deletes one and whatever still waits to be sent to it:
curl -X DELETE https://app.kadmo.ai/api/v1/webhooks/12 \
-H "Authorization: Bearer $KADMO_API_TOKEN"It answers { "id": 12, "deleted": true }. Another member's subscription, another account's and a missing id all answer 404 webhook_not_found. An automation platform subscribes when its trigger is turned on and deletes the subscription when it is turned off.
The subscribe's 201 names the subscription's own address in its Location header, https://app.kadmo.ai/api/v1/webhooks/12: a DELETE to it with the same token ends the subscription. Power Automate and Logic Apps delete a trigger's subscription that way when a flow is turned off (see Power Automate and Copilot Studio).
Whose it is
A subscription belongs to the member whose token made it. It lists and is deleted through that member's tokens, and an admin sees and deletes every member's on the Integrations page (In the app).
| What happens | The subscription |
|---|---|
| The token that made it is revoked | Stays. It is the member's, not the token's: delete it if the automation is gone. |
| Its member is removed from the account | Is deleted. |
| Its workspace is archived | Stays, and receives nothing from it. |
| Its workspace is deleted | Is deleted. |
| The trial ends | Keeps receiving. A new subscription is refused; a delete works. |
The events
| Event | Sent when | And |
|---|---|---|
job.finished | A job ends: succeeded, failed or cancelled, as GET /jobs/{id} reads it, a playbook's steps included. | It waits until the job's files and report have arrived: between 30 seconds and 10 minutes after the end. |
job.needs_input | A job waits on a person: a question of its agent, or a gate's approval. | It waits two minutes after the ask and is sent only if the ask is still open. Each ask is its own event. |
task.done | A task reads done: its run resolved, or closed with nothing to do. | A failed or cancelled task sends no task.done; its jobs send job.finished. |
Only what happened after the subscription was made is sent. A job that was requeued and ends again is sent again, for its new end.
A delivery
POST https://hooks.example.com/kadmo
Content-Type: application/json
User-Agent: Kadmo-Webhooks/1
Kadmo-Event: job.finished
Kadmo-Delivery: 9812
Kadmo-Timestamp: 1794540000
Kadmo-Signature: v1=32b828787d27a69f5b37560ab18af0de066b426caa2608d05acbebdd458bb7c3{
"id": 9812,
"type": "job.finished",
"api_version": "v1",
"created_at": "2026-11-13T09:31:02.000Z",
"webhook_id": 12,
"data": {
"job": {
"id": 9001,
"status": "succeeded",
"workflow": "se-work",
"result": { "verdict": "PASS", "summary": "Fixed the redirect.", "pull_requests": [], "evidence": [] },
"url": "https://app.kadmo.ai/jobs/8123"
}
}
}| Field | What it is |
|---|---|
id | The delivery's id. It is the same on every retry of the delivery: drop a repeat by it. |
type | The event, as Kadmo-Event names it; ping for a test delivery. |
api_version | v1. Fields are added to a payload, never renamed or removed. |
created_at | When the payload was made, before its first attempt. Every retry sends the same body. |
webhook_id | The subscription it was sent to. |
data.job | For the two job events: the job exactly as GET /jobs/{id} answers it (the Job). For job.needs_input, its needs_input holds the question, the answers the agent offered, when it asked, and the link where it is answered. |
data.task | For task.done: the task exactly as GET /tasks/{key} answers it (the Task). |
Answer any 2xx within 10 seconds to take the delivery. Kadmo reads no more than the start of your answer and follows no redirect.
Verify a signature
Every delivery is signed with the subscription's secret, so a receiver can tell it came from Kadmo and was not changed. Check it before you act on a delivery:
- Read
Kadmo-Timestampand the body exactly as received, as bytes, before any JSON parsing. - Refuse the delivery when the timestamp is more than five minutes from your clock.
- Join the timestamp, a full stop and the body:
<Kadmo-Timestamp>.<body>. - Compute the HMAC-SHA256 of that string with the secret as the key, written as lower-case hex.
Kadmo-Signatureholds one or morev1=<hex>values separated by commas. Accept the delivery when your value equals any of them, compared in constant time.
The same computation from a shell, with the secret in $KADMO_WEBHOOK_SECRET, the header in $TS and the body in $BODY:
printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$KADMO_WEBHOOK_SECRET"The value it prints, after v1=, is the signature.
Retries
A delivery that is not answered with a 2xx is tried again: eight attempts in all, the first when the event is ready, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 6 hours 24 minutes, the last 24 hours after the first. A Retry-After longer than the next wait is kept, up to an hour. After the eighth attempt the delivery has failed.
| Your endpoint answers | Kadmo |
|---|---|
2xx | Takes the delivery as delivered. |
410 Gone | Stops: the subscription is disabled at once. Answer 410 when an automation is gone for good. |
A redirect (3xx) | Retries, and never follows it. |
| Any other status, nothing in 10 seconds, or a TLS or connection failure | Retries. |
Deliveries are sent at least once: a delivery your endpoint took but did not answer in time is sent again with the same id. They can also arrive out of order. Use id to drop repeats, and the object's own status and times rather than the order of arrival.
When a subscription is disabled
A subscription is disabled when its endpoint took nothing for 24 hours: a delivery used all eight attempts and nothing reached the endpoint since that delivery's first try. A 410 disables it at once. An endpoint that refuses one payload but takes the others stays on.
When it is disabled, nothing more is sent to it, the deliveries waiting for it are dropped, and its member gets one e-mail saying why. Turn it on again with Enable on the Integrations page; what happened while it was off is not sent later. GET /api/v1/webhooks reads its status and disabled_reason (failing or gone).
In the app
The Integrations page (app.kadmo.ai/integrations) lists the subscriptions under Outgoing webhooks, after the groups of cards: an admin sees every member's, with whose it is, and a member sees their own. Each row shows the endpoint, the events, the workspace, the token that made it, its state (Active, Failing, Disabled) and its last delivery. There is no form to create one: a subscription is made through the API.
| Action | What it does |
|---|---|
| Deliveries | The last seven days of deliveries: the event, the job or task, Delivered, Retrying, Waiting, Failed or Dropped, the attempts and the next try, and the last answer with its first characters. |
| Send test | Sends one ping ("data": {}) to the endpoint, signed like any delivery and tried once. It never disables the subscription and is not its last delivery. One test per subscription every ten seconds. |
| Enable | Turns a disabled subscription on again. |
| Delete | Deletes the subscription. |
Troubleshooting
| You see | Why | What to do |
|---|---|---|
422 invalid_webhook_url for http://localhost:5678/… | A webhook URL must be https and public | For a local n8n or a test server, expose it through a public HTTPS tunnel and subscribe the tunnel's address. |
| Nothing arrives | The event has not happened since you subscribed, or the subscription is disabled | Press Send test on the Integrations page, then open Deliveries. |
Retrying with HTTP 401 or HTTP 403 | Your endpoint refuses the call | Check the endpoint's own access settings. Kadmo sends no credentials of its own besides the signature. |
| The signature does not match | The body was parsed or re-serialized before the check, or the secret is another subscription's | Verify against the body exactly as received, with the secret this subscription was created with. |
| The same event twice | A retry after a timeout | Drop the repeat by its id. |
| Disabled | Every delivery failed for 24 hours, or the endpoint answered 410 | Fix the endpoint, then press Enable. |