Webhooks

A schedule webhook is a public URL that runs an agent’s schedule when called — from CI/CD, a CRM, monitoring or any system that can make an HTTP request. No ExoHuman account is needed by the caller: a 256-bit opaque token in the URL is the credential.

Create a webhook

Open the agent’s Schedules tab, expand a schedule and click Webhook:

1. Enable webhook mints the URL. Use Reveal / Copy URL and the ready-made curl example.
2. Rotate URL issues a new token — the old URL stops working immediately.
3. Revoke turns the webhook off.

Anyone who can manage the agent’s schedules can manage its webhook. The agent must exist and be live.

Calling it

curl -X POST https://acme.exohuman.cc/api/webhooks/<token> \
  -H 'Content-Type: application/json' \
  -d '{"context": "Deploy 4213 finished on production"}'

• The response is 202 Accepted; the run happens asynchronously.
• The body is optional. context (up to 4,000 characters) is appended to the schedule’s message so the agent knows what happened.
• Bodies larger than 16 KiB are rejected with 413.
• Send an Idempotency-Key header if your caller may deliver the same event twice; a repeat within 24 hours returns the first result instead of firing again.
• Rate limits: 10 calls per minute per token and 60 calls per minute per client IP; over the limit returns 429.

Signature authentication (recommended)

By default, anyone with the URL can trigger the schedule. Turn on Signature authentication to require proof of a shared secret:

1. In the webhook panel, under Signature authentication, click Enable. The signing secret (whsec_…) is shown once; it is stored encrypted.
2. Each request must carry X-ExoHuman-Signature: sha256=<hex>, where <hex> is the HMAC-SHA256 of the raw request body with the secret. Missing or invalid signatures get 401.
3. Rotate secret issues a new one; Disable removes it. Rotating the URL also clears the secret.

SECRET='whsec_xxxxxxxx'
BODY='{"context":"deploy 4213 finished"}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)"
curl -X POST 'https://acme.exohuman.cc/api/webhooks/<token>' \
  -H 'Content-Type: application/json' \
  -H "X-ExoHuman-Signature: $SIG" \
  -d "$BODY"

Management API

Endpoint	Method	Purpose
/api/agents/{name}/schedules/{id}/webhook	POST	Create or rotate the token
/api/agents/{name}/schedules/{id}/webhook	GET	Status and URL
/api/agents/{name}/schedules/{id}/webhook	DELETE	Revoke
/api/agents/{name}/schedules/{id}/webhook/secret	POST	Enable or rotate signature auth (secret returned once)
/api/agents/{name}/schedules/{id}/webhook/secret	DELETE	Disable signature auth
/api/webhooks/{token}	POST	Public trigger

Every webhook call is recorded in the audit log with caller IP, schedule and agent. Webhook runs start a new chain, so they never count toward agent-to-agent depth limits.

Outgoing events

To react to things that happen inside ExoHuman, use event subscriptions between agents, or stream security events to your SIEM from the audit log.