Webhooks

Webhooks let you receive real-time notifications at your own URL when subscribed events occur. Use them to forward events to your SIEM, build approval workflows, notify on-call, or trigger automations.

​

Prerequisites

• Unbound account with Admin role
• A public HTTPS endpoint you control to receive the events
• (Optional) A server-side secret manager to store the signing secret

​

Setup

1. In your Unbound dashboard, go to Settings → Webhooks
2. Click Add Endpoint
3. Enter your endpoint URL (must be https://, public, and not pointing at a private network)
4. Optionally add a description
5. Select one or more events to subscribe to (or Select all)
6. Click Create

On creation, your endpoint’s whsec_… signing secret is shown once. Copy it now and store it in your secret manager. You can reveal it again from the endpoint detail page if you need to, but treat it like an API key.

​

Signature verification

Every delivery includes three headers your receiver can use to verify the event came from Unbound and wasn’t tampered with in transit. The verification algorithm is standard HMAC-SHA256:

1. Strip the whsec_ prefix from your signing secret and base64-decode the remainder. The result is the HMAC key.
2. Build the signed payload by concatenating <webhook-id>.<webhook-timestamp>.<raw-body>.
3. Compute HMAC-SHA256(key, signed_payload) and base64-encode the digest. Prefix it with v1,.
4. Compare against the webhook-signature header using a constant-time comparison. Multiple signatures may be space-separated; accept if any one matches.
5. Reject deliveries whose webhook-timestamp is older than 5 minutes to prevent replay.

​

Event types

Each command or tool call can fire multiple events. The four per-action events fire whenever a policy of that action matches, and *.logged fires for everything. A command that matched a Block policy therefore produces two deliveries: *.blocked and *.logged. You can subscribe to specific events, an entire group (terminal_command.*, mcp_tool.*, or secrets.*), or all events (*). *.logged is the firehose — every classified command or tool call. Use it for SIEM streaming; pick the per-action events if you only want policy-driven activity.

​

Payload

Every event uses the same envelope: a top-level id (ULID, prefixed msg_), type (the event name), timestamp (ISO-8601, UTC), and a nested data block. The data block is consistent across all event types within a family — terminal-command events carry a command string, MCP-tool events carry mcp_server, mcp_tool, and mcp_parameters instead, and everything else is shared. A single command or tool call can trigger multiple events (e.g. a blocked command fires both *.blocked and *.logged). Each event is a separate delivery with its own id and signature, but they share the same data.tool_use_id so you can dedupe across events if you want one record per command. Secrets events (secrets.blocked / secrets.audited) don’t carry tool_use_id — use request_id to dedupe those.

​

Field reference

​

Retries

Failed deliveries (anything that isn’t HTTP 200–299) retry on the following schedule: The retry horizon is approximately 28 hours total. Each attempt times out after 15 seconds. After 8 failed attempts the event is dropped.

​

Custom headers

You can attach static custom headers to every delivery for your endpoint — useful when your receiver requires a specific authentication header. To add custom headers, click your endpoint in the dashboard, then Custom headers → Edit. Reserved headers (content-type, user-agent, host, and our signature headers) cannot be overridden.

​

Testing

To send a test event:

1. Open your endpoint from Settings → Webhooks
2. Click Send test event
3. Pick an event type from the dropdown
4. Click Send

The test event uses the same signing pipeline and headers as a real event. Failed test deliveries are not retried so you can iterate quickly on your receiver. Test deliveries appear in the Message Attempts table tagged with test.

​

Managing endpoints

From the endpoint detail page you can:

• Edit subscribed events — change which events trigger this endpoint
• Edit description — update the human-readable label
• Edit custom headers — change static headers sent on every delivery
• Disable — stop firing without losing history (use the three-dot menu)
• Delete — remove the endpoint and its delivery history permanently

The Success rate (24h) column on the endpoints list shows the percentage of HTTP 2xx responses in the last 24 hours. A dash means no deliveries in that window.

​

Troubleshooting