Webhooks

Documentation Index

Fetch the complete documentation index at: https://docs.getunbound.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Webhooks fire only when high-risk activity is detected. The event name is derived from the matched policy action; if no policy matched but the activity was still flagged as high-risk, you receive a .flagged event. You can subscribe to specific events, an entire group (terminal_command.* or mcp_tool.*), or all events (*).

​

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.

​

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