Skip to content
Open the app

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:

bash
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"] }'
json
{
  "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_…"
}
FieldWhat it takes
urlAn 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.
eventsAt least one of job.finished, job.needs_input and task.done.
workspaceOptional. 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 withWhen
422 invalid_webhook_urlThe 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_unavailableThe host could not be looked up just now. Retry after Retry-After.
404 workspace_not_found, 409 workspace_archivedThe workspace is not the account's, or it is archived.
409 webhook_limit_reachedYou hold 100 subscriptions already.
402 trial_expiredThe 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:

bash
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 happensThe subscription
The token that made it is revokedStays. It is the member's, not the token's: delete it if the automation is gone.
Its member is removed from the accountIs deleted.
Its workspace is archivedStays, and receives nothing from it.
Its workspace is deletedIs deleted.
The trial endsKeeps receiving. A new subscription is refused; a delete works.

The events ​

EventSent whenAnd
job.finishedA 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_inputA 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.doneA 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 ​

text
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
json
{
  "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"
    }
  }
}
FieldWhat it is
idThe delivery's id. It is the same on every retry of the delivery: drop a repeat by it.
typeThe event, as Kadmo-Event names it; ping for a test delivery.
api_versionv1. Fields are added to a payload, never renamed or removed.
created_atWhen the payload was made, before its first attempt. Every retry sends the same body.
webhook_idThe subscription it was sent to.
data.jobFor 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.taskFor 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:

  1. Read Kadmo-Timestamp and the body exactly as received, as bytes, before any JSON parsing.
  2. Refuse the delivery when the timestamp is more than five minutes from your clock.
  3. Join the timestamp, a full stop and the body: <Kadmo-Timestamp>.<body>.
  4. Compute the HMAC-SHA256 of that string with the secret as the key, written as lower-case hex.
  5. Kadmo-Signature holds one or more v1=<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:

bash
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 answersKadmo
2xxTakes the delivery as delivered.
410 GoneStops: 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 failureRetries.

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.

ActionWhat it does
DeliveriesThe 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 testSends 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.
EnableTurns a disabled subscription on again.
DeleteDeletes the subscription.

Troubleshooting ​

You seeWhyWhat to do
422 invalid_webhook_url for http://localhost:5678/…A webhook URL must be https and publicFor a local n8n or a test server, expose it through a public HTTPS tunnel and subscribe the tunnel's address.
Nothing arrivesThe event has not happened since you subscribed, or the subscription is disabledPress Send test on the Integrations page, then open Deliveries.
Retrying with HTTP 401 or HTTP 403Your endpoint refuses the callCheck the endpoint's own access settings. Kadmo sends no credentials of its own besides the signature.
The signature does not matchThe body was parsed or re-serialized before the check, or the secret is another subscription'sVerify against the body exactly as received, with the secret this subscription was created with.
The same event twiceA retry after a timeoutDrop the repeat by its id.
DisabledEvery delivery failed for 24 hours, or the endpoint answered 410Fix the endpoint, then press Enable.