Skip to main content

Receive and verify webhooks

Public API

Every webhook delivery is an HTTP POST with a JSON body and a signature computed from that body with your endpoint's signing secret. Verify the signature first; everything else follows from a body you can trust.

Who can use it: anyone who runs an HTTPS endpoint the platform can reach. Registering the endpoint and reading its deliveries is done on the Webhooks tab of the Developer Hub by a Builder or higher, in a tenant licensed for the public API.

VideoWebhooks3:04

Recorded on .

  1. Register an endpoint

    On the Developer Hub's Webhooks tab, select Add endpoint, enter the HTTPS URL, tick the events and select Save endpoint. Copy the signing secret; it is shown once.

  2. Verify each delivery

    Compute the HMAC-SHA256 of the raw body with the secret and compare it to X-Katonic-Signature in constant time; the Verify signatures snippets on the tab do this in Python and Node.

  3. Read the deliveries log

    Under Recent deliveries, open an attempt to read its status code or error, the body your receiver returned and how long it took.

Prerequisites​

  • An endpoint registered on the Webhooks tab, with the events it should receive ticked. See Webhooks.
  • Its signing secret, which the platform shows once when the endpoint is saved. If it is lost, delete the endpoint and add it again.

Accept, verify, answer​

  1. Read the delivery. The body is compact JSON with four fields: id (the delivery's event id, starting with evt_), type (the event name, such as evaluation.completed), timestamp (UTC, ISO 8601, ending in Z) and data (the event's own fields). Three headers accompany it: X-Katonic-Signature, X-Katonic-Event (the same value as type) and X-Katonic-Delivery (the same value as id).

    {"id":"evt_3f9c...","type":"evaluation.completed","timestamp":"2026-09-10T17:42:11Z","data":{"run_id":"...","agent_id":"..."}}
  2. Verify the signature. Compute an HMAC-SHA256 of the raw request body bytes with the secret, take the hex digest, and compare it to X-Katonic-Signature with a constant-time comparison. Hash the bytes exactly as received: parsing and re-serialising the JSON changes the spacing and the signature no longer matches.

    import hashlib, hmac

    def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")
    import { createHmac, timingSafeEqual } from "node:crypto";

    export function verify(rawBody, header, secret) {
    const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
    const a = Buffer.from(expected), b = Buffer.from(header || "");
    return a.length === b.length && timingSafeEqual(a, b);
    }

    Read the body as bytes before any JSON middleware touches it; most frameworks expose the raw body if you ask for it before parsing.

  3. Answer quickly, work later. The platform posts to your endpoint with a ten-second timeout and records the status code it received. Return a 2xx as soon as the signature verifies, put the event on a queue, and do the work afterwards. A non-2xx answer or a timeout is recorded as a failed delivery.

  4. Handle repeats and pairs. Treat id as the idempotency key and ignore a delivery you have already processed. One platform event can arrive as two public events: a workflow pausing for approval is delivered as both workflow.paused and approval.requested, each with its own id. Endpoints subscribed to the same event are called one after another, so do not assume two systems see an event at the same instant.

Read the deliveries log​

Recent deliveries on the Webhooks tab lists each attempt with the event, the status code or the error, its duration, the body that was sent and the first part of your response. It reads No deliveries yet until an event fires.

Verify​

Creating and revoking an API key each fire an event (key.created, key.revoked), so an endpoint subscribed to them can be exercised without waiting for a workflow or an evaluation: create a throwaway key, watch the delivery arrive and verify, then revoke it.

Troubleshooting​

  • The signature never matches: you hashed a re-serialised body, used the wrong secret, or compared against the wrong header. Log the length of the raw body you hashed and compare it with the body recorded in Recent deliveries.
  • No deliveries arrive: the endpoint is Paused or disabled, is not subscribed to the event, or is not reachable from the platform over HTTPS; a private address receives nothing and the log shows the failures.
  • Deliveries are marked failed with no status code: the request timed out or the connection failed; the error column says which.
  • The same event arrives twice: expected; dedupe on id.

Describes the platform as of .

Was this page helpful?