Webhooks

Webhooks let Kadryn deliver events to your systems.

Use webhooks when an external service needs to react to Kadryn events such as alerts, reports, exports, delivery states, integration changes or governance activity.

What you can do

The Webhooks page lets you:

• create webhook endpoints;
• subscribe endpoints to event types;
• inspect endpoint readiness;
• send test webhooks;
• view recent deliveries;
• redeliver failed events;
• rotate webhook secrets;
• inspect event catalog entries;
• identify failing or quarantined endpoints.

Endpoint requirements

A webhook endpoint should:

• use HTTPS;
• be reachable from Kadryn;
• verify Kadryn signatures;
• parse JSON safely;
• respond quickly;
• return 2xx only after accepting the event;
• process heavy work asynchronously;
• be idempotent.

Create an endpoint

Open:

Developers → Webhooks

Then create an endpoint with:

• a name;
• an HTTPS URL;
• selected event types;
• active status.

Kadryn may show readiness as missing, waiting for delivery, degraded or ready.

Event subscriptions

You can subscribe an endpoint to one or more event types.

If no specific event selection is configured, your workspace may treat the endpoint as subscribed to the default catalog. Prefer explicit subscriptions for production endpoints.

Test delivery

Use a test webhook when:

• you create a new endpoint;
• you rotate a secret;
• your endpoint was failing;
• you change event subscriptions;
• you deploy a new receiver.

After sending a test, inspect the delivery result and endpoint logs.

Delivery states

| State | Meaning | | --- | --- | | success | The endpoint accepted the event. | | pending | Delivery has not completed yet. | | retrying | Kadryn will try again. | | failed | Delivery failed and may need action. | | abandoned | Delivery will not be retried automatically. |

Endpoint states

| State | Meaning | | --- | --- | | active | Endpoint can receive events. | | paused | Endpoint is intentionally paused. | | disabled | Endpoint is disabled. | | failing | Recent deliveries failed. | | quarantined | Endpoint is protected from further unsafe delivery. |

Redelivery

Use redelivery when a delivery failed because of a temporary endpoint problem.

Before redelivering:

• fix the endpoint;
• check signature verification;
• check rate limits;
• verify event handling is idempotent;
• review recent failures.

Receiver example

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyKadrynSignature(input: {
  readonly rawBody: string;
  readonly timestamp: string;
  readonly signature: string;
  readonly secret: string;
}): boolean {
  const payload = `${input.timestamp}.${input.rawBody}`;
  const expected = createHmac("sha256", input.secret)
    .update(payload)
    .digest("hex");

  const left = Buffer.from(input.signature, "hex");
  const right = Buffer.from(expected, "hex");

  return left.length === right.length && timingSafeEqual(left, right);
}

Use the full verification guide before deploying a receiver.

Security rules

Do:

• verify signatures;
• reject stale timestamps;
• keep webhook secrets server-side;
• rotate secrets after exposure;
• process events idempotently;
• return quickly;
• log delivery IDs and event IDs.

Do not:

• trust unsigned payloads;
• process events before verification;
• store webhook secrets in client code;
• block the request while running long jobs;
• retry non-idempotent side effects without a dedupe key.

Troubleshooting

Endpoint stays `missing_endpoint`

Create at least one active HTTPS endpoint.

Readiness is `waiting_for_delivery`

Send a test webhook or wait for a real event.

Readiness is `degraded`

Inspect failing deliveries, response status, latency, endpoint state and signature verification.

Deliveries keep failing

Check receiver logs, HTTPS availability, signature verification, response status and processing time.

Related pages

• Webhook signatures
• Errors
• Rate limits
• Webhook failures