Skip to navigation
Run agents

Receive run webhooks

Register a signed webhook for one run, verify each lifecycle notification on your receiver, and list or delete registrations.
View as Markdown

Register a webhook for a specific run to receive lifecycle notifications.

The current service requires a configured signing secret and an allowlisted public HTTPS destination on port 443. Arrange destination approval and receiver verification configuration with Sikaru before registering; the API does not return a per-webhook signing secret.

Signed lifecycle notification Verify signature, freshness, deduplicate deliveryId 2xx after durable acceptance Process asynchronously Fetch run and events when more detail is needed Sikaru Your receiver Your application

Sikaru sends a signed notification. Your receiver verifies it, stores it durably, returns 2xx, and processes the work later. Fetch the run through the SDK when you need more detail.

Register a webhook

webhook = client.run_webhooks.create_webhook(
    project,
    run_id=run_id,
    url="https://your-approved-host.example/sikaru/events",
    idempotency_key="case-42-webhook",
)["webhook"]

Replace the example URL with your approved receiver. Registration needs runs:create; listing uses runs:read.

Receiver contract

Notifications contain deliveryId, projectId, runId, and an event with id, sequence, and type. They contain lifecycle metadata rather than arbitrary event payloads. Fetch the run and its events through the authenticated SDK when you need more detail.

HeaderContent
Sikaru-Delivery-IdThe delivery ID.
Sikaru-TimestampThe timestamp used in the signature.
Sikaru-Signaturev1= followed by the hex HMAC-SHA256 of the timestamp, a period, and the exact raw request body.

Use the receiver secret agreed with Sikaru; never use your API key as the signing secret.

Your receiver should:

  1. Verify the signature using a constant-time comparison before parsing or acting on the body.
  2. Enforce a timestamp freshness policy.
  3. Durably deduplicate on deliveryId.
  4. Return a 2xx response only after accepting the notification durably.
  5. Process slower business work asynchronously.

Delivery can repeat. The service makes bounded attempts, and redirects are not followed. Do not depend on webhooks as your only way to learn a run’s final state: reconcile with run status and event polling after an outage.

Manage registrations

registrations = client.run_webhooks.list_webhooks(project)
client.run_webhooks.delete_webhook(project, webhook["id"])

Deleting a registration stops future delivery from it; it does not cancel the run or undo notifications already delivered. CLI equivalents are under sikaru run-webhooks.

Next steps

Runs and tool requests

Poll run status and events to reconcile final state.

Authentication

Set up the API key your SDK uses to fetch run details.