Webhook Callback Contract

​

Overview

​

Supported events

​

Callback request

POST /managedagent/webhooks HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Bailian-ManagedAgent-Webhook/1.0
webhook-id: whe_01JXX8JY9BBM4BK4C2P7K3M3ZR
webhook-timestamp: 1785810621
webhook-signature: v1,BASE64_HMAC_SHA256

​

Signature verification

signed_content = webhook-id + "." + webhook-timestamp + "." + raw_body
secret_bytes = Base64Decode(RemovePrefix(signing_secret, "whsec_"))
signature = Base64(HMAC-SHA256(secret_bytes, UTF8(signed_content)))

• The value of webhook-id is the outer event.id, not the webhook_id of the Webhook configuration.
• signing_secret is whsec_ plus standard Base64 text. When verifying, strip the whsec_ prefix and decode the remainder with standard Base64; do not use the full whsec_... string directly as the HMAC key.
• Read the unmodified raw request body to verify the signature first, then perform JSON deserialization.
• Verify that the timestamp is within 5 minutes of the current time, and use a constant-time comparison to verify the signature.

​

Event envelope fields

{
  "type": "event",
  "id": "whe_01JXX8JY9BBM4BK4C2P7K3M3ZR",
  "created_at": "2026-08-06T10:30:21.123Z",
  "data": {
    "id": "sesn_xxx",
    "type": "session.status_idled",
    "workspace_id": "ws_xxx"
  }
}

{
  "type": "event",
  "id": "whe_01JXX8JY9BBM4BK4C2P7K3M3ZR",
  "created_at": "2026-08-06T10:30:21.123Z",
  "data": {
    "id": "sesn_xxx",
    "type": "session.thread_idled",
    "workspace_id": "ws_xxx",
    "session_thread_id": "sthread_xxx"
  }
}

​

Idempotency, retry, and delivery guarantees

• Possible duplicates: The same event may be delivered multiple times, always with the same event.id; deduplicate idempotently by that identifier.
• No ordering guarantee: Events may arrive out of order; sort by created_at when ordering is required, and treat the resource query result as the source of truth for final state.
• Query retention: Delivered events are retained for 7 days, after which they can no longer be queried.

​

Verification example

import base64
import hashlib
import hmac
import os
import time

secret = os.environ["AGENT_WEBHOOK_SECRET"]
secret_bytes = base64.b64decode(secret[len("whsec_"):])

def verify_webhook(raw_body: bytes, webhook_id: str, timestamp: str, signature_header: str) -> bool:
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False

        version, signature = signature_header.split(",", 1)
        if version != "v1":
            return False

        signed_payload = f"{webhook_id}.{timestamp}.".encode() + raw_body
        expected = base64.b64encode(
            hmac.new(secret_bytes, signed_payload, hashlib.sha256).digest()
        ).decode()
        return hmac.compare_digest(signature, expected)
    except (TypeError, ValueError):
        return False