POST
/api/agents/webhooksbearer tokenSubscribe to agent events
Push instead of poll. Register a URL and the events you care about, and every one arrives signed so you can prove it came from us.
Try it
curl -X POST "https://storkie.ai/api/agents/webhooks" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"YOUR_AGENT_ID","url":"https://your.app/hooks/storkie","events":["lead.captured"]}'No Run button: this needs your bearer token, and a docs page that asks for one is teaching people to paste credentials into web forms.
Request body
| Name | Type | Description |
|---|---|---|
idrequired | string | The agent ID. |
urlrequired | string | Your HTTPS endpoint. |
eventsrequired | array | Any of `conversation.reply`, `lead.captured`, `action.performed`. |
Response
| Name | Type | Description |
|---|---|---|
hookrequired | object | The created subscription. |
secretrequired | string | Shown ONCE. Used to verify the signature. |
Worth knowing
- Verify `X-Storkie-Signature` — an HMAC-SHA256 of the raw body with your secret. Compare it with a constant-time function; a plain `===` leaks timing.
- Delivery URLs go through the same SSRF check as every other outbound fetch: DNS is resolved and private, loopback, link-local and metadata addresses are refused.
Rate limit
20 requests / minute / account
Errors
400— A URL that is not public HTTPS, or an unknown event name.401— Missing or invalid token.
Questions
What if my endpoint is down?
Delivery is retried with backoff. Persistent failure disables the hook rather than retrying for ever.
Can I point it at localhost while developing?
No — private addresses are refused. Use a tunnel that gives you a public HTTPS URL.