Inbound webhooks

An Inbound Webhook automation gives you a URL and API key; any system that can send a JSON POST can start a session.

How it works

1. Create an automation with Trigger Type set to Inbound Webhook.
2. After creation, copy the Webhook URL and API Key shown on the page.
3. Send an authenticated POST with a JSON body.
4. OpenInspect checks the request against the automation's conditions and, if they pass, starts a session whose prompt is your saved instructions followed by a context block containing the payload.

Webhook automations do not use a schedule or timezone.

Setup notes

• The Webhook URL and API Key appear only after the automation is created. The page shows a Copy button next to each and a Copy curl button that produces a ready-to-run test request.
• The API key is shown once: the form warns you to save it because it is not shown again after you leave the page. Only a hash is stored.
• If the key is lost or leaked, click Regenerate Key on the detail page. The old key stops working immediately and the new key is displayed once.
• The detail page always shows the webhook path (POST /webhooks/automation/<automation-id>) for reference.

Request requirements

Example:

curl -X POST "https://<your-worker-url>/webhooks/automation/<automation-id>" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"event":"deploy.failed","service":"api","environment":"prod"}'

What the agent receives

The session prompt is your instructions, then a separator, then a context block, then a guardrail line telling the agent to treat the context as untrusted. The context block contains:

• A line stating the automation was triggered by an inbound webhook.
• The time the request was received.
• The JSON payload, pretty-printed and truncated after 4,096 characters.
• A warning that the payload is untrusted input data, not instructions.

Write instructions that tell the agent which payload fields matter and what to do with them. For example:

A deployment event has arrived (see the payload below). If `event` is
"deploy.failed", check out the commit named in `sha`, run the test suite,
and open a pull request with a fix if a test fails. Otherwise do nothing.

Filtering with conditions

Webhook automations support one condition type, JSONPath Filter. A condition holds one or more filters; every filter must match for the run to start. Add filters with Add filter in the condition builder.

Operators

A missing path fails every operator except exists. When you type a numeric value in the filter box it is stored as a number, so $.count = 3 compares against the number 3, not the string "3".

Path syntax

Paths are simple dot notation starting with $., for example $.event.type or $.deployment.environment.

Not supported:

• Array indexing such as $.items[0]
• Recursive descent such as $..id
• Filter expressions or any other full JSONPath syntax

Examples

Idempotency and duplicate deliveries

If your sender may retry, include a top-level idempotencyKey string in the body.

• Deliveries that share an idempotencyKey are treated as the same event. Re-sending it does not create a second run; the duplicate is counted as skipped.
• The idempotencyKey stays in the stored body but is removed from the context block the agent sees.
• Without an idempotencyKey, every delivery gets its own key, so separate deliveries to the same automation can run concurrently.

Responses

A successful request returns:

{ "ok": true, "triggered": 1, "skipped": 0, "steered": 0 }

A request whose conditions do not match returns ok: true with triggered: 0.

Error responses

A paused automation accepts the request but starts nothing.

Security

• Treat the API key like a password. Anyone holding it can start sessions against the automation's repository under the owner's authority. Use Regenerate Key if it is exposed.
• The payload reaches the agent as untrusted data inside the prompt. Keep instructions specific about which fields to act on, and do not ask the agent to follow instructions contained in the payload.
• Runs execute with the automation owner's permissions; the sender's identity is not checked beyond the key.

Troubleshooting

Next steps

• Sentry alerts
• GitHub event triggers
• Secrets