On Honcho Cloud, register endpoints from the dashboard. The webhook API
below is available on self-hosted instances; on
api.honcho.dev it returns
405 Method Not Allowed. Use the
Webhooks page instead. Everything else on
this page — payload shapes, delivery semantics — applies to both.Registering an Endpoint
200 with the existing endpoint, a new one returns 201. The test
route emits a test.event to every endpoint on the workspace, which is the
quickest way to confirm your receiver and signature check work end to end.
Choosing Event Types
Passevent_types to receive only some events:
- Leave
event_typesout, or sendnull, to receive every event type. An endpoint’sevent_typesisnullin responses when it receives everything. - To change an existing endpoint, register the same URL again. Sending
event_typesreplaces its list,nullresets it to every type, and leaving the field out keeps the list it has. - The list can’t be empty, and each entry must be an event type from
Events other than
test.event, spelled exactly as listed there: names are case-sensitive. Anything else returns422. - The list is checked when an event is delivered, so a change also applies to events that are already queued but not yet sent.
test.eventalways reaches every endpoint, whatever its list, so the test route can check any endpoint.
Webhook management is also available in the dashboard on the
Webhooks page.
URL Requirements
A webhook URL must be absolute and usehttp or https. URLs whose host is an
IP literal in a private, loopback, link-local, reserved, multicast, or
unspecified range are rejected with 422.
Each workspace can register up to WEBHOOK_MAX_WORKSPACE_LIMIT endpoints
(default 10). Exceeding the limit returns 409.
Events
Payload
Every delivery is aPOST with a Content-Type: application/json body in this
envelope:
tenant_id identifying which tenant the event belongs to.
data is event-specific — its keys differ by event type. A test.event
carries only workspace_id:
null — on queue.empty, that’s session_id, observer, and observed for
work that isn’t tied to a session or an observer pair. Across event types the key
is simply absent.
Parse defensively: branch on type as the discriminator, treat every data key
as optional rather than required, and tolerate new event types and new fields.
A parser that requires the queue.empty keys on every event will break on a
test.event.
Verifying Signatures
Each delivery carries anX-Honcho-Signature header: the hex-encoded
HMAC-SHA256 of the raw request body, keyed with your deployment’s
WEBHOOK_SECRET. Always compare with a constant-time function, and always sign
the bytes you received — Honcho serializes the body compactly with sorted keys,
so re-serializing your parsed JSON will not reliably reproduce it.
Delivery Semantics
Delivery is best-effort and fire-and-forget:- Events fan out to all of the workspace’s endpoints concurrently.
- Each request has a 30-second timeout.
- There are no retries. A non-2xx response, a timeout, or a connection error is logged on the server and the event is dropped.
Self-Hosting Requirements
Webhook delivery is queued work handled by the deriver process, so a deriver worker must be running for events to be sent. See Configuration forWEBHOOK_SECRET and WEBHOOK_MAX_WORKSPACE_LIMIT.
Queue Status
Poll background processing state instead of waiting for a push
Webhook API Reference
Full request and response schemas for the webhook endpoints