Skip to content
Browse the docs

Webhooks

Turn inbound HTTP requests into Nested tasks: route, HMAC or token verification, Go-template task bodies with .JSON fields, deliveries, and redelivery.

Updated 3 min readView as MarkdownOpen in Nested

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#

  1. Select Create hook and enter a Hook name.
  2. Deployment: choose the agent that receives the tasks. Nested skips this step inside an agent’s settings. You cannot change the target later.
  3. 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.
  4. Verification: choose a mode (see below).
  5. 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.
  6. Secret: copy the secret now. It is never shown again.

The ingress URL has this shape:

text
https://<your-nested-host>/hooks/g/<deploy-key>/<segment>/<segment>

Verification modes#

ModeHow 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 tokenSend 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.
bash
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:

FieldValue
.MethodHTTP method (GET, POST, …)
.PathFull request path
.RouteMatched route form, such as /hooks/g/billing/{env}
.PathParamsMap of {param} values from the path
.QueryFirst value of each query parameter
.QueryAllAll values of each query parameter
.HeadersRequest headers
.ContentTypeContent-Type header
.BodyRaw request body as a string
.JSONParsed body when the content type is JSON; empty otherwise
.Providergeneric, slack, or github
.EventTypeProvider event type, such as the GitHub event name; empty for generic hooks
.DeliveryIDNested’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.