Skip to content
Kindgi

Get a webhook when a run finishes

View as Markdown

This guide has Kindgi send your app a signed run.finished request each time a run ends, so your app needn't poll.

Kindgi signs each request with a secret that your receiver knows too. The secret lives with your other secrets, and the endpoint refers to it by name. Kindgi never stores it with the endpoint.

This guide is about Kindgi sending your app webhooks. To have a webhook from another system start a run, see Start runs from WooCommerce, Drupal or any signed webhook.

Before you start

Section titled “Before you start”
  • kindgi dev running in your pack's directory, with Kindgi 0.1's CLI.
  • A flow to watch, registered on that runtime. This guide filters on acme.check-order-stock; use your own flow's id.
  • Your app's server, on Node 22.12 or later, Python 3.11 or later, or Java 17 or later, with Kindgi 0.1's client and KINDGI_API_URL and KINDGI_API_TOKEN set.
  • A route in your app that receives the request, such as http://localhost:8787/hooks/kindgi. Verify a webhook has receivers to start from.

1. Store a signing secret

Section titled “1. Store a signing secret”

Kindgi and your receiver both need the same secret: Kindgi signs with it, and your receiver checks the signature.

A signing secret is whsec_ and the base64 of at least 24 random bytes. Generate one:

scripts/new-webhook-secret.ts
import { generateWebhookSecret } from '@kindgi/sdk/webhooks';


console.log(generateWebhookSecret());

It prints a new secret on one line: whsec_ and the base64 of 32 random bytes.

Store it as a secret, under a name. The CLI asks for the value and doesn't echo it:

Terminal window
pnpm exec kindgi secrets set ACME_WEBHOOK_SECRET --env=local --scope=tenant --app
  • ACME_WEBHOOK_SECRET is the secret's name. The endpoint refers to it by this name.
  • --env=local is the environment the secret belongs to. Under kindgi dev, local is the pack's env files.
  • --scope=tenant is where the secret lives: the tenant, rather than one org (org:<orgId>) or project (project:<projectId>).
  • --app writes it to your app's own env file, .env.local, where your receiver reads it. Kindgi reads it there too. Without --app, it goes to Kindgi's own .kindgi/secrets.env, which your app doesn't load, as Keep local values in env files explains.

It prints the secret's name, scope, environment and version as JSON, then:

…
  Set ACME_WEBHOOK_SECRET at tenant in local, in your app's env file.
Excerpt

In a deployment, store it in that deployment's secrets store, under its environment's name, with kindgi secrets. Your receiver needs the same value, from its own configuration.

2. Register the endpoint

Section titled “2. Register the endpoint”

The endpoint tells Kindgi where to send the request, and with which secret.

There's no CLI command for webhook endpoints. Register one with the client, from your app or a script. Ask your coding agent: "I want Kindgi to send my app a webhook when a run of my flow finishes." For reference, the code looks like this:

scripts/register-webhook.ts
import { createClient } from '@kindgi/sdk/client';


const kindgi = createClient(); // KINDGI_API_URL, KINDGI_API_TOKEN


const endpoint = await kindgi.webhookEndpoints.create({
  url: 'http://localhost:8787/hooks/kindgi',
  events: ['run.finished'],
  secretRef: { envName: 'local', name: 'ACME_WEBHOOK_SECRET' },
  filter: { flowIds: ['acme.check-order-stock'] }, // optional
});
console.log(endpoint.endpointId, endpoint.url);

It prints the endpoint's id and URL:

5c1d2267-4dc8-4bd6-81e8-940e620405ea http://localhost:8787/hooks/kindgi

  • url is your receiver. Use https in production; plain http is for development. In kindgi dev, localhost reaches your machine, not the runtime's container. Outside development, the receiver must be on a public address. A self-hosted runtime whose receiver is on its own private network, such as the same VPC or compose network, sets KINDGI_WEBHOOK_PRIVATE_NETWORKS=allow. That opens RFC 1918, CGNAT, and IPv6 unique-local and site-local addresses, still over https only. Loopback and the cloud metadata addresses stay refused. A URL the deployment refuses gets 400 webhook-url-refused with a reason. For a private address, it's The deployment refuses this URL: private network addresses are not allowed.

  • events lists the events to send: run.finished here. improvement-pass.finished and approval.requested are the others, as Webhook events and deliveries describes.

  • secretRef names the secret: the environment it's in, local in development, and its name. Kindgi checks that it exists and is strong enough, and keeps only the name. A secret that isn't stored is refused:

    {"error":{"code":"webhook-secret-not-found","message":"No secret \"NOPE_SECRET\" in \"local\": store it first, then register the endpoint",…}}
    Excerpt

  • filter (optional) narrows which runs reach the endpoint. flowIds names flows, any version of them. projectId names a project. includeDryRuns: true sends dry runs too, which are left out otherwise. Without a filter, every run you start reaches the endpoint.

Only runs your app or the CLI started send run.finished. The runs inside them, such as an agent step's turn, don't.

3. What your endpoint receives

Section titled “3. What your endpoint receives”

When a run of acme.check-order-stock ends, your URL gets a POST:

POST /hooks/kindgi
content-type: application/json
user-agent: Kindgi-Webhooks/1
webhook-id: d7bc2805-587c-4830-a36f-fddeb0b7a423
webhook-timestamp: 1791058584
webhook-signature: v1,bj8Mj6s7ln2Gd1sDRQi8+Wax2SOFHovsdMIwvNhDrgw=
{
  "id": "d7bc2805-587c-4830-a36f-fddeb0b7a423",
  "type": "run.finished",
  "createdAt": "2026-10-03T20:16:24.554Z",
  "data": {
    "run": {
      "id": "c24869c1-9243-4531-920b-d657e05eac0b",
      "projectId": "bc654965-c4fb-4667-85f1-33e46f4a4f0c",
      "flowId": "acme.check-order-stock",
      "flowVersion": "0.1.0",
      "status": "completed",
      "dryRun": false,
      "failureMessage": null,
      "createdAt": "2026-10-03T20:16:24.465Z",
      "completedAt": "2026-10-03T20:16:24.554Z",
      "usage": {
        "calls": 0,
        "costUsd": 0,
        "tokens": { "prompt": 0, "completion": 0, "cacheRead": 0, "cacheWrite": 0, "reasoning": 0 }
      }
    }
  }
}
  • status is completed, failed or cancelled. failureMessage says why a run failed.
  • usage is what the run's model calls cost. This flow calls no model, so it's all zeros.
  • The event carries the run's identity and outcome, never its input or output. Fetch the run with runs.get for its output.
  • webhook-id is the event's id, the same on every retry.

Webhook events and deliveries has every field, and the event for an agent's run.

4. Answer the request

Section titled “4. Answer the request”

Kindgi retries any request your receiver doesn't answer with success, so the receiver answers each one.

Check the signature, then answer with a 2xx status. Deduplicate on webhook-id, since the same event can arrive twice. Verify a webhook has receivers that do both.

Your app now handles each event once, from a request whose signature it has checked.

Next

Section titled “Next”