Webhooks
Turn inbound HTTP requests into Nested tasks: route, HMAC or token verification, Go-template task bodies with .JSON fields, deliveries, and redelivery.
Systems that are not Nested still need to start work. A webhook is an ingress URL on your Nested installation. When something calls it, Nested verifies the request, renders a task from it with a Go template, and starts that task on an agent.
You can create a webhook as a Webhook trigger in Automations, or as a raw hook on one agent from its settings → Automations → Webhooks. The raw hook wizard is described here.
Before you start#
- Own the agent you want the tasks to go to.
- Decide how callers will authenticate. Use HMAC when the caller can sign the body.
Steps#
- Select Create hook and enter a Hook name.
- Deployment: choose the agent that receives the tasks. Nested skips this step inside an agent’s settings. You cannot change the target later.
- Route: pick the HTTP method (or Any method), the Deploy key (the first path segment; use a fixed name for stable URLs), and 0–3 Path segments, which can be literal or
{param}placeholders. Check the Ingress URL preview. - Verification: choose a mode (see below).
- Task: enter the task name, pick a workspace — or leave it unspecified to create one from the event — and write the message body. Use Simple mapping or Advanced template.
- Secret: copy the secret now. It is never shown again.
The ingress URL has this shape:
https://<your-nested-host>/hooks/g/<deploy-key>/<segment>/<segment>Verification modes#
| Mode | How callers authenticate |
|---|---|
| HMAC signature (Recommended) | Send X-Hook-Signature with the hex HMAC-SHA256 of the raw body, computed with the hook secret. A sha256= prefix is accepted. |
| Bearer token | Send the secret as Authorization: Bearer <secret>. The X-Hook-Token header and the secret query parameter also work. |
| None (insecure) | Anyone who knows the URL can start tasks. You must type the hook name to confirm. |
BODY='{"id":"inv_42","total":100}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$HOOK_SECRET" | cut -d' ' -f2)
curl -X POST "https://<your-nested-host>/hooks/g/billing/invoice" \
-H "Content-Type: application/json" \
-H "X-Hook-Signature: sha256=$SIG" \
-d "$BODY"Template fields#
The task template is a Go text/template. These fields are available:
| Field | Value |
|---|---|
.Method | HTTP method (GET, POST, …) |
.Path | Full request path |
.Route | Matched route form, such as /hooks/g/billing/{env} |
.PathParams | Map of {param} values from the path |
.Query | First value of each query parameter |
.QueryAll | All values of each query parameter |
.Headers | Request headers |
.ContentType | Content-Type header |
.Body | Raw request body as a string |
.JSON | Parsed body when the content type is JSON; empty otherwise |
.Provider | generic, slack, or github |
.EventType | Provider event type, such as the GitHub event name; empty for generic hooks |
.DeliveryID | Nested’s internal delivery id |
Functions include dig (nested lookup, for example {{ dig .JSON "comment" "body" }}), default, coalesce, lower, upper, replace, toJSON, parseJSON, quote, b64enc, and b64dec. In the hook’s template editor, Presets load starting templates (Generic JSON, Slack mention, GitHub push, GitHub pull request), Input reference inserts fields, and Test render previews the result without creating a task.
Deliveries#
On the hook’s detail page, View deliveries lists recent events with their status: Received, Dispatched, Render failed, Dispatch failed, Unrouted, or Duplicate. Open one to see the request, body, rendered envelope, and tasks, and select Redeliver to create a new task from the same event. Rotate secret replaces the secret; the old one stops working immediately.
Example#
A billing system POSTs {"id":"inv_42","total":100}. With the task name Invoice {{ .JSON.id }} and the body Check invoice {{ .JSON.id }} for {{ .JSON.total }} EUR against the ledger., Nested starts a task named “Invoice inv_42”.
Questions
- Why does my template render an empty value?
- JSON fields live under
.JSON. Use{{ .JSON.field }}or{{ dig .JSON "a" "b" }}instead of{{ .field }}. - I lost the webhook secret. Can I see it again?
- No. Secrets are shown once. Select Rotate secret to issue a new one; the old secret stops working immediately.
- Can I replay a webhook delivery?
- Yes. Open the delivery under View deliveries and select Redeliver. Nested creates a new task from the same event.