Receive webhooks from other services
A hook is a URL on your distribution — https://acme-marketing.edge.deca-dev.com/_hooks/stripe — that accepts webhooks from another service. Edge checks the sender's signature, ignores repeats of the same event, and turns each accepted request into a hook.received event you can forward or act on.
Creating a hook does not change the live site. A hook only answers once the distribution has a live deployment. The web app does not manage hooks yet. Use an agent, the CLI, or the API.
1. Create the hook
Pick the preset that matches the sender. The secret is the one the sender gave you.
Add a Stripe webhook receiver called stripe to acme-marketing. The signing secret is whsec_8Qp…edge hooks create acme-marketing --slug stripe --preset stripe --secret 'whsec_8Qp…'curl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "slug": "stripe", "preset": "stripe", "secret": "whsec_8Qp…" }'The agent runs edge_hook_create. The response has the URL to give the sender:
{
"hook_id": "hk_2b9e4c1d7a0f4e6b8c3d5a1f9e7b0c42",
"slug": "stripe",
"preset": "stripe",
"url": "https://acme-marketing.edge.deca-dev.com/_hooks/stripe",
"enabled": true,
…
}Edge stores the secret encrypted and never returns it. Presets: standard-webhooks, stripe, github, slack, line, shopify, hmac and token. See Presets.
A sender that cannot sign — a CI job, a cron, a no-code tool — uses the token preset. Edge generates a secret path segment and shows the full URL once:
{ "url": "https://acme-marketing.edge.deca-dev.com/_hooks/ci/vQ0m3Lr9…", "token_shown_once": true, … }2. Point the sender at the URL
Paste the URL into the sender's webhook settings (Stripe dashboard, GitHub repository settings, LINE Developers console, …) and send a test event from there. Slack's URL verification is answered automatically.
3. Check what arrived
Show the last receipts for the stripe hook on acme-marketing.edge hooks receipts acme-marketing hk_2b9e4c1d7a0f4e6b8c3d5a1f9e7b0c42curl -s https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/stripe/receipts \
-H "Authorization: Bearer $EDGE_TOKEN"[
{
"receipt_id": "rcpt_9a1f0e…",
"idempotency_key": "evt_1QhZ3k2eZvKYlo2C",
"key_source": "provider",
"status": "succeeded",
"received_at": "2026-10-11T03:20:11Z",
…
}
]A request rejected by the signature check gets 401 and leaves no receipt. If nothing shows up, check the secret and that the distribution is live.
Duplicates and idempotency keys
Senders retry. Edge recognises a retry by its idempotency key: the sender's own event id when the preset has one (Stripe's evt_…, GitHub's delivery id), otherwise an Idempotency-Key header. The first request with a key is processed; a repeat gets 200 with "replay": true, the original receipt_id, and Edge-Idempotent-Replay: true, and nothing runs twice.
If you send requests yourself, include a key:
curl -s -X POST https://acme-marketing.edge.deca-dev.com/_hooks/ci/vQ0m3Lr9… \
-H "Idempotency-Key: build-1842" \
-H "Content-Type: application/json" \
-d '{"ref": "main", "status": "passed"}'To check whether Edge already has a key, run edge hooks receipt acme-marketing hk_2b9e4c1d7a0f4e6b8c3d5a1f9e7b0c42 build-1842 (the agent runs edge_hook_receipt_get) or call GET /v1/distributions/{id}/hooks/{hook}/receipts/build-1842. "found": false means Edge has not seen it in the last 7 days.
Clear the cache or promote on a webhook
A hook can also act on the distribution. This changes the live site. A hook has at most one action: a cache clear, a promote, or a function runtime (next section).
- Clear the cache when a CMS publishes:
"config": {"action": {"kind": "invalidate", "paths": ["/blog/*"]}} - Promote the newest ready deployment when CI passes:
"config": {"action": {"kind": "promote_latest"}}
Make the ci hook on acme-marketing promote the newest ready deployment.edge hooks update acme-marketing ci --config - <<'EOF'
{"action": {"kind": "promote_latest"}}
EOFcurl -s -X PATCH \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/ci \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "config": { "action": { "kind": "promote_latest" } } }'The receipt's result shows what happened, for example {"promoted": "01M2QB6J…"}, or {"promoted": null} when there was nothing newer to promote. To undo a promote, see Promote and roll back.
Run a function runtime on a webhook
A hook can instead run one of the distribution's function runtimes on every accepted request. Edge checks the signature and drops repeats first, so your code only sees verified, new events. Build the function runtime first, then point the hook at its script_id:
"config": {"action": {"kind": "wasm", "script_id": "01JB7Q2M5V8K3N6P9R1T4W7Y0Z"}}
Make the stripe hook on acme-marketing run my order-sync function for every event.edge hooks update acme-marketing stripe --config - <<'EOF'
{"action": {"kind": "wasm", "script_id": "01JB7Q2M5V8K3N6P9R1T4W7Y0Z"}}
EOFcurl -s -X PATCH \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/stripe \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "config": { "action": { "kind": "wasm", "script_id": "01JB7Q2M5V8K3N6P9R1T4W7Y0Z" } } }'The function runtime must belong to the same distribution. Your code receives a POST to /_hooks/{name} whose body is the hook.received event, the same JSON a webhook subscribed to hook.* gets. The sender's payload is in data.payload, a few of its headers in data.headers, and the key Edge deduplicated on in data.idempotency_key. The function keeps the same document, file, and store grants as a direct invoke.
{
"id": "evt_01JB7R…",
"type": "hook.received",
"distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
"data": {
"hook_slug": "stripe",
"idempotency_key": "evt_1QhZ3k2eZvKYlo2C",
"payload": { "id": "evt_1QhZ3k2eZvKYlo2C", "type": "checkout.session.completed", … }
},
…
}The code runs after Edge has answered the sender with 200, so its response never goes back to the sender. A 2xx marks the receipt succeeded and anything else failed. The receipt's result holds status_code, the version that ran, and function_event_id. What the code printed is in the function runtime's logs (edge_function_logs) under that event id, with source: "hook".
Edge runs the code once per idempotency key. If the worker restarts in the middle of a run, it can run a second time, so make the code safe to repeat, keyed on data.idempotency_key.
Queue it or start a workflow
A hook can also put each request on a queue, start a workflow run, or resume a waiting run. See Buffer webhooks into a queue or a workflow.
Forward the payload
Every accepted request emits hook.received with the payload. To pass it on — to an agent platform, a queue, your backend — subscribe a webhook to hook.*, optionally with "filters": {"hook_slug": "stripe"}. See Send Edge events to a webhook. Edge checks the sender's signature once and signs the forwarded event with its own.