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

In your Unbound dashboard, go to Settings → Webhooks
Click Add Endpoint
Enter your endpoint URL (must be https://, public, and not pointing at a private network)
Optionally add a description
Select one or more events to subscribe to (or Select all)
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.

Header	Description
`webhook-id`	Unique idempotency key (`msg_…`). Use it to deduplicate retries.
`webhook-timestamp`	Unix seconds when we signed the payload. Reject deliveries more than ~5 minutes old to prevent replay.
`webhook-signature`	`v1,<base64-hmac-sha256>` computed over `${webhook-id}.${webhook-timestamp}.${raw-body}` using your signing secret as the HMAC key.

The verification algorithm is standard HMAC-SHA256:

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

Always verify against the raw request body bytes, not a re-serialised JSON object. JSON re-serialisation can reorder keys or change whitespace, breaking the signature.

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.

Event	Fires when
`terminal_command.blocked`	A terminal command matched a Block policy
`terminal_command.warned`	A terminal command matched a Warn policy
`terminal_command.slack_approval_requested`	A terminal command is awaiting Slack approval
`terminal_command.audited`	A terminal command matched an Audit policy
`terminal_command.logged`	Every terminal command observed by Unbound
`mcp_tool.blocked`	An MCP tool call matched a Block policy
`mcp_tool.warned`	An MCP tool call matched a Warn policy
`mcp_tool.slack_approval_requested`	An MCP tool call is awaiting Slack approval
`mcp_tool.audited`	An MCP tool call matched an Audit policy
`mcp_tool.logged`	Every MCP tool call observed by Unbound
`secrets.blocked`	A request was blocked by a Secrets policy
`secrets.audited`	A request matched an audit-only Secrets policy
`ai_tool.unsanctioned_detected`	An unsanctioned AI coding tool was found on a user’s device, the first time it’s seen for that user
`ai_tool.unsanctioned_used`	A user used an unsanctioned AI coding tool. Rate-limited to at most once every 24 hours per user and tool, so it won’t fire on every request

You can subscribe to specific events, an entire group (terminal_command.*, mcp_tool.*, secrets.*, or ai_tool.*), 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. The ai_tool.* events are your Shadow AI feed: they fire when a tool that isn’t on your sanctioned list turns up in the fleet. Route them somewhere a human will see them.

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. Shadow AI events (ai_tool.*) describe a tool on a device, not a single command, so they carry their own set of fields — see Shadow AI events below. They don’t carry tool_use_id, and there’s no per-command grouping to do: each delivery is a distinct alert. Deduplicate retries by webhook-id like any other event.

Field reference

Field	Type	Description
`tool_use_id`	string	Stable per-command identifier (prefixed `tu_`). The same value appears on every event fired for the same command — use it to dedupe across overlapping subscriptions (e.g. an endpoint subscribed to both `.blocked` and `.logged` receives two deliveries with the same `tool_use_id`).
`tool`	string \| null	The AI tool that issued the call (e.g. `claude-code`, `cursor`, `codex`, `copilot`).
`tool_name`	string	The specific tool name. For terminal commands this is `Bash`, `Edit`, etc.; for MCP calls it’s `<server>__<tool>`.
`user_email`	string \| null	The email of the user whose AI tool fired the call.
`prompt`	string \| null	The user’s original prompt that led to this activity. Useful for context.
`thread_id`	string \| null	Conversation thread ID for grouping related events.
`intent_attribution`	string	`USER_INTENTIONAL`, `AGENT_INITIATED`, or `UNKNOWN` — whether the user explicitly asked for this or the agent decided autonomously.
`command`	string	(terminal only) The literal command string.
`mcp_server`	string	(MCP only) The MCP server the tool call targeted.
`mcp_tool`	string	(MCP only) The specific tool within that server.
`mcp_parameters`	object	(MCP only) The parsed arguments passed to the tool.
`matched_policies`	array	Every policy that matched this event. Empty on `*.logged` events when no policy matched. Each entry contains `id`, `name`, `action`, `policy_type`.
`classifications`	array	All command families this event was classified into (compound commands can produce multiple). Each entry has `command_family`, `confidence_score`, `targets`.
`guardrail`	string	(secrets only) The DLP guardrail that matched — always `Secrets`.
`action`	string	(secrets only) `BLOCK` or `AUDIT`.
`model`	string \| null	(secrets only) The model the request targeted.
`request_id`	string \| null	(secrets only) The gateway request identifier.
`detections`	array	(secrets only) Each detected secret. Each entry has `type` (`API Key`, `Cryptographic Key`, or `Database Connection String`) and `confidence`.
`detection_count`	number	(secrets only) Number of entries in `detections`.
`user_prompt`	string \| null	(secrets only) The user’s prompt that triggered the detection. May contain the flagged value.
`log_url`	string	(secrets only) Deep link to the matching entry in the Data Security log.

Shadow AI events

ai_tool.unsanctioned_detected and ai_tool.unsanctioned_used report an unsanctioned tool on a user’s device, so their data block is different from the command events above.

{
  "id": "msg_01J9Z...",
  "type": "ai_tool.unsanctioned_detected",
  "timestamp": "2026-07-02T12:00:00Z",
  "data": {
    "tool_name": "Cursor",
    "app_label": "cursor",
    "sanctioned": false,
    "organization_id": 123,
    "user_id": 4567,
    "user_full_name": "Vignesh Subbiah",
    "device_id": 8910,
    "detection_count": 1,
    "first_detected_at": "2026-07-02T12:00:00+00:00",
    "last_detected_at": "2026-07-02T12:00:00+00:00",
    "source": "gateway_runtime",
    "request_id": "req_...",
    "model": "claude-opus-4-8"
  }
}

Field	Type	Description
`tool_name`	string	The unsanctioned tool that was found (e.g. `Cursor`).
`app_label`	string	The tool’s identifier (e.g. `cursor`).
`sanctioned`	boolean	Always `false` on these events — that’s why they fired.
`user_id`	number	The user the tool belongs to. Present on every event; use it to route the alert even when you have no email.
`user_full_name`	string	The user’s name, for display in an alert.
`device_id`	number \| null	The device the tool was found on. Use it to route the alert to the affected endpoint. `null` if the device couldn’t be resolved.
`detection_count`	number	How many times this tool has been seen for this user. `1` on first detection, and climbing on `unsanctioned_used`.
`first_detected_at`	string	When this tool was first seen for this user (ISO-8601, UTC).
`last_detected_at`	string	When it was most recently seen (ISO-8601, UTC).
`organization_id`	number	Your organization.
`source`	string	Where the sighting came from.
`request_id`	string \| null	The gateway request that surfaced it, when there was one.
`model`	string \| null	The model the tool was calling, when known.

Deduplicating. To drop duplicate deliveries of the same event, use webhook-id — the idempotency key on every delivery, exactly as you would for any other event.Do not build a longer-lived idempotency key out of user_id + tool_name. These events are deliberately recurring: unsanctioned_detected fires once, the first time a tool is seen for a user, and unsanctioned_used fires at most once every 24 hours for the same user and tool for as long as they keep using it. Two unsanctioned_used deliveries share the same user_id and tool_name but are different alerts — collapsing on those fields would suppress the recurring-usage signal, which is the point of the event. They carry no tool_use_id and are not a per-command feed; treat each delivery as its own alert and key only retries on webhook-id.

Retries

Failed deliveries (anything that isn’t HTTP 200–299) retry on the following schedule:

Attempt	Delay since previous
1	(immediate)
2	5 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	5 hours
7	10 hours
8	10 hours

The retry horizon is approximately 28 hours total. Each attempt times out after 15 seconds. After 8 failed attempts the event is dropped.

Redirects (3xx) are treated as failures and not followed. Configure your endpoint to be the resolved URL.

Custom headers

You can attach static custom headers to every delivery for your endpoint — useful when your receiver requires a specific authentication header.

Receiver	Header
Splunk HEC	`Authorization: Splunk <hec-token>`
Datadog Logs Intake	`DD-API-KEY: <key>`
Sumo Logic HTTP Source	(no header — URL is the credential)
Tines	(no header — URL secret is the credential)
Slack incoming webhook	(no header — URL is the credential)

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:

Open your endpoint from Settings → Webhooks
Click Send test event
Pick an event type from the dropdown
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

Why isn't my endpoint receiving events?

Verify the endpoint is Enabled, the events you expect are in Subscribed events, and the URL is reachable from the public internet. Use Send test event to confirm end-to-end connectivity. If you want to confirm any traffic is flowing, subscribe to terminal_command.logged and mcp_tool.logged — the firehose events fire for every classified call regardless of risk or policy match. Then double-check the Terminal Runs table on the Tool Use page for the activity you expected.

Signature verification fails on every event

The most common cause is verifying against a parsed JSON object instead of the raw body bytes. Make sure your handler reads the raw request body before parsing. Also confirm you copied the full whsec_… secret without truncation.

My receiver is slow / times out

Process the event asynchronously. Acknowledge with 200 immediately and queue the actual work — anything taking longer than 15 seconds will be treated as a failure and retried.

I want to replay an old event

Delivery history is visible per-endpoint, but events are not currently replayable through the UI. Re-trigger the source action in your AI tool, or contact support to manually replay a specific delivery.

Tool Policies

Configure which actions trigger which event types

Slack

Pair webhooks with Slack approval workflows

Getting Started

CLI

Policies

Analytics

Hooks API

Integrations

MDM Integrations

Connections

Support & Troubleshooting

Prerequisites

Setup

Signature verification

Event types

Payload

Field reference

Shadow AI events

Retries

Custom headers

Testing

Managing endpoints

Troubleshooting

Tool Policies

Slack

​Prerequisites

​Setup

​Signature verification

​Event types

​Payload

​Field reference

​Shadow AI events

​Retries

​Custom headers

​Testing

​Managing endpoints

​Troubleshooting

Tool Policies

Slack

Prerequisites

Setup

Signature verification

Event types

Payload

Field reference

Shadow AI events

Retries

Custom headers

Testing

Managing endpoints

Troubleshooting