Webhooks are how your product hears about agent activity it did not directly trigger. When a thread completes overnight, an approval request comes in, a schedule fires, or a connection is detached, the runtime delivers an HTTP POST to a URL you control instead of waiting for you to poll. A subscription is fleet-scoped. One URL can listen to a curated subset of event types or all of them. The secret is returned only when the subscription is created or rotated, so capture it then; the API will not show it again.Documentation Index
Fetch the complete documentation index at: https://docs.cerca.dev/llms.txt
Use this file to discover all available pages before exploring further.
Delivery model
Deliveries are at-least-once over HTTPS. Each request times out after 10 seconds. A failed attempt — network error,429, or 5xx — is retried once after a 1 second delay; everything else is delivered exactly once. Because retries can produce duplicates, your handler should be idempotent. The X-Agent-Delivery-Id header is stable across retries of the same delivery and is the right key to dedupe on.
Every request is signed. The X-Agent-Signature header carries an HMAC-SHA256 of {timestamp}.{payload} using your subscription secret, prefixed with sha256=. The X-Agent-Timestamp header carries the same timestamp the signature was computed over, which lets you reject replays whose drift exceeds your tolerance window.
Ordering is not guaranteed. Two events about the same thread may arrive out of order, and a retried delivery can land after a later event. Treat each event as a fact about a moment in time and reconcile against your own state when ordering matters.
When to use webhooks
Use webhooks when the reaction needs to happen without a user watching — sending a notification after a long-running thread finishes, recording an audit trail, fanning aschedule.triggered event out to your own queue. Use thread streaming, not webhooks, for foreground UX where a user is actively waiting on the agent.
Approvals are the canonical webhook use case: an approval.requested event tells your product to surface a decision to the right human, and approval.resolved lets you continue once the decision lands.
For the full set of events Cerca emits and their payload shapes, see the event reference. For a step-by-step receive path with signature verification, see Receiving webhooks.