# Webhooks

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

Section: Automations · Updated: 2026-11-19 · Canonical: https://nested.me/docs/webhooks

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](https://nested.me/docs/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

| 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. |

```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:

| 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 |

> [!WARNING]
> Fields from a JSON body live under `.JSON`. Write `{{ .JSON.id }}` or `{{ dig .JSON "id" }}`; a bare `{{ .id }}` renders nothing.

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.

[Open in Nested](https://app.nested.me/automations)

## Related

- [Automations](https://nested.me/docs/automations)
- [GitHub](https://nested.me/docs/github)
- [Security model](https://nested.me/docs/security)
