Skip to main content

Webhooks

Lifecycle webhooks POST a signed JSON event to your HTTPS endpoint when a run starts, runs a tool, finishes or fails. Use them for audit logs, alerts or analytics. They cannot change the run. For that, use hooks.

These are not the provider webhooks that bring chat messages in. Those are covered in Channels.

broods/index.ts
import { defineAgent, env } from "broods";

export const agent = defineAgent({
name: "agent",
hooks: {
webhooks: [
{
enabled: true,
url: "https://example.com/agent-events",
secret: env("WEBHOOK_SECRET"),
events: [
"agent.started",
"tool.call.finished",
"agent.finished",
"agent.failed",
],
},
{
enabled: true,
url: "https://audit.example.com/events",
secret: env("AUDIT_WEBHOOK_SECRET"),
events: ["agent.failed"],
},
],
},
});
FieldDescription
enabledTurns delivery on for this entry
urlPublic HTTPS endpoint
secretHMAC signing secret
eventsEvents to send. Omit it to send all of them.

Every enabled entry whose events match gets its own delivery. Private, loopback, link-local and internal hosts are rejected when you save and again at delivery. Redirects are not followed.

You can also add, toggle and remove webhooks in the dashboard under Settings, Webhooks, which needs the org admin role. The signing secret is write-only there. broods agent get <name> lists them.

Events​

EventSent when
agent.starteda run starts
agent.step.finisheda model step finishes
agent.finishedthe agent produces its final answer
agent.failedthe run fails
agent.approval.requireda tool waits for approval
tool.call.starteda tool call starts
tool.call.finisheda tool call finishes or fails
tool.resulttool results from a step are available
subagent.task.starteda subagent task starts
subagent.task.finisheda subagent task finishes or fails

Payload and signature​

{
"type": "tool.call.finished",
"timestamp": "2026-05-17T20:00:00.000Z",
"accountId": "acct_...",
"agentId": "agent_...",
"eventId": "acct:...:api:...",
"conversationKey": "acct:...:conversation:...",
"payload": { "success": true }
}

Each request carries X-Webhook-Signature: sha256=<hex>, the HMAC-SHA256 of the raw body with your secret. Verify it before trusting the body:

import { createHmac, timingSafeEqual } from "node:crypto";

function isValid(rawBody: string, header: string, secret: string): boolean {
const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;

return (
header.length === expected.length &&
timingSafeEqual(Buffer.from(header), Buffer.from(expected))
);
}

Delivery is best effort. A failed delivery is logged and never fails the run.

The webhook demo is a runnable example.