How-toadvancedadmin
Webhook Setup Guide
Configure outbound webhooks to integrate Botonom with your stack.
3 min read4,900 viewsUpdated 2026-07-10
JuliaGuide Assistant
In this article you'll learn about Creating a webhook, then explore Verifying webhook signatures, and finally review Delivery, retries and auto-disable.
Creating a webhook
Create a subscription through the API (or try it in the Playground):
curl -X POST "https://api.botonom.com/en/api/v1/webhooks/create/" \
-H "X-Botonom-Api-Key: bk_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.yourapp.com/botonom",
"events": ["agent.command.completed", "agent.command.failed"]
}'
The response includes the signing secret whsec_... exactly once - store it now. The URL must be https.
Available events:
agent.command.completed- a command run finished;data.result_textcarries the agent's replyagent.command.failed- a command run failed
Delivery payload shape:
{
"id": "evt_a1b2c3d4e5f60718",
"event": "agent.command.completed",
"created_at": "2026-07-10T07:26:45+00:00",
"data": {
"run_id": "cmd_654741d0...",
"agent_id": "<agent-uuid>",
"agent_name": "Joshua",
"status": "completed",
"instruction": "...",
"result_text": "..."
}
}
Verifying webhook signatures
Every delivery carries an X-Botonom-Signature header in the form t=<unix>,v1=<hex>, where v1 = HMAC_SHA256(secret, t + "." + rawBody). Verify it with your whsec_ secret:
const crypto = require('crypto');
function verifyBotonomWebhook(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(
signatureHeader.split(',').map((p) => p.split('='))
);
const expected = crypto
.createHmac('sha256', secret)
.update(parts.t + '.' + rawBody)
.digest('hex');
// optionally reject if parts.t is older than a few minutes (replay protection)
return crypto.timingSafeEqual(
Buffer.from(parts.v1),
Buffer.from(expected)
);
}
Always verify signatures in production and compute the HMAC over the RAW request body, not a re-serialized JSON object.
Delivery, retries and auto-disable
Return any 2xx to acknowledge a delivery. Anything else (or a timeout over 5 seconds) counts as a failure.
- Failed deliveries retry automatically: after 2m → 10m → 30m → 2h (max 5 attempts). Each attempt is re-signed with a fresh timestamp.
- A successful delivery resets the subscription's failure counter.
- 20 consecutive failures auto-disable the subscription (it shows
active: falseinwebhooks/list). To re-enable, delete and recreate it.
During development, point the subscription at a request-inspection service to see headers and payloads, then verify your signature code against a real delivery.
webhookintegration
Was this helpful?
More questions? Contact support