Get notified with webhooks

​

Events

• "*" subscribes to the session.status_updated firehose.
• Each subscribed type is delivered separately: with both session.status_updated and session.failed, a failure sends two deliveries.
• List the types programmatically with List event types.

​

Delivery payload

{
  "type": "session.status_updated",
  "id": "evt_5d1f0c9e8a7b4c2da93f1e6b8c4d2a70",
  "created_at": "2026-06-11T15:04:05.123Z",
  "data": {
    "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "completed",
    "previous_status": "running"
  }
}

​

Verifying deliveries

from hai_agents import verify_webhook

event = verify_webhook(raw_body, signature_header, timestamp_header, secret="whsec_...")
if event.type == "session.status_updated":
    print(event.data["session_id"], event.data["status"])

import { verifyWebhook, type WebhookEventData } from "hai-agents";

const event = verifyWebhook(rawBody, signatureHeader, timestampHeader, "whsec_...");
if (event.type === "session.status_updated") {
  const data = event.data as unknown as WebhookEventData;
  console.log(data.session_id, data.status);
}

​

Delivery semantics

• Deduplicate. The event id and X-H-Webhook-Delivery are stable across retries.
• Ignore arrival order. A retried old event can land after a newer one. Trust status, previous_status, and created_at.
• Return 2xx fast. Do slow work after responding.
• Treat it as a trigger. Fetch the authoritative state with Get session status.

​

Testing an endpoint

​

Rotating the secret

1. Pass ["whsec_old", "whsec_new"] to the verify helper as soon as you have the new secret. Deliveries rejected in between are retried.
2. Once deliveries verify against the new secret, remove the old one.

​

Constraints

• Target URLs must be https:// and resolve to a public address. A HEAD request checks reachability when you register or change the URL. Deliveries to private or internal hosts fail and count as failed attempts.
• The secret is returned only by Create and Rotate.
• Up to 10 webhooks per organization.
• A disabled webhook stays registered but receives nothing.
• After 50 consecutive failed attempts, a webhook is disabled. Fix the receiver, then re-enable it with Update ({"disabled": false}).