Events, webhooks, and hooks
Webhooks send Edge events to your HTTPS endpoint. Hooks receive webhooks from other services at https://{slug}.edge.deca-dev.com/_hooks/{hook}. Both are configured with an agent or the HTTP API; the web app does not manage them yet. Agents can read this same information from the edge://webhooks MCP resource.
See Events and webhooks for how the pieces fit, and Environments and domains for hosts.
Event types
| Type | Class | Sent when | data fields |
|---|---|---|---|
deployment.created | lifecycle | A deployment was created, including by a rollback | deployment_id, from_deployment_id |
deployment.ready | lifecycle | The preview is published | deployment_id, preview_url |
deployment.failed | lifecycle | The deployment could not be published | deployment_id |
deployment.promoted | lifecycle | The live site moved to this deployment | deployment_id, previous_deployment_id, schedule_id (when a schedule promoted it) |
deployment.scheduled | lifecycle | A promote, takedown or restore was scheduled | schedule_id, action, deployment_id, run_at |
deployment.schedule_cancelled | lifecycle | A pending schedule was cancelled | schedule_id, action, deployment_id, run_at |
deployment.schedule_failed | lifecycle | A schedule could not run: its deployment was not ready, it was more than a day late, or an error | schedule_id, action, deployment_id, run_at, error |
distribution.created | lifecycle | A distribution was created | slug |
distribution.updated | lifecycle | Distribution settings changed | changes — the top-level setting names that differ |
distribution.taken_down | lifecycle | Live hosts now answer 410 Gone or a temporary redirect | mode, location, schedule_id |
distribution.restored | lifecycle | A takedown was lifted | schedule_id |
distribution.destroyed | lifecycle | A distribution was deleted | slug |
domain.verified | lifecycle | Domain ownership was verified | fqdn, status |
domain.active | lifecycle | The domain serves traffic with a certificate | fqdn, status |
domain.failed | lifecycle | Verification or provisioning failed | fqdn, status |
domain.attached | lifecycle | The domain was attached to a distribution | fqdn |
domain.detached | lifecycle | The domain was detached | fqdn |
function.build.succeeded | lifecycle | A function runtime build published a new version | script_id, version |
function.build.failed | lifecycle | A function runtime build failed | script_id |
cron.fired | lifecycle | A cron with the emit target ran (one event per run) | job_id, attempt, owner_kind, owner_id, scheduled_for |
cron.run.failed | lifecycle | A cron run failed and has no retries left | cron_id, name, job_id, attempt, error_code |
cron.run.missed | lifecycle | A cron slot was reached more than a day late and was not run | cron_id, name, job_id, scheduled_for |
queue.backlog.high | lifecycle | A queue holds more than 10,000 messages, or its oldest has waited over an hour (at most once an hour per queue) | queue_id, name, depth, oldest_ready_age_seconds, depth_threshold, age_threshold_seconds |
queue.message.dead_lettered | data | A queue message used its last attempt and is now dead | queue_id, name, message_id, attempts, error, job_id, body |
workflow.completed | lifecycle | A workflow run's step answered done | run_id, name, script_id, step |
workflow.failed | lifecycle | A workflow run failed: a step answered fail, ran out of retries, timed out waiting with no timeout step, or the run expired | run_id, name, script_id, step, error, error_code |
form.submitted | data | /_submit stored a form submission | form_id, submission_id, path, envelope (with files when the form takes uploads) |
form.file.scanned | data | A file attached to a submission finished its scan: clean, rejected or scan_failed. Sent once per file | form_id, submission_id, file |
hook.received | data | A hook accepted a verified request | hook_id, hook_slug, preset, receipt_id, idempotency_key, key_source, headers, payload |
goal.converted | volume | A human visit matched a conversion goal a subscription selects | goal_id, goal_slug, goal_type, analytics_event_id, session_hash, path, event_name, source, utm_source, utm_medium, utm_campaign, country, deployment_id, converted_at |
webhook.subscription.created | security | A webhook subscription was created | webhook_id, url_host, event_types |
webhook.subscription.disabled | security | A subscription was turned off after repeated failures | webhook_id, url_host, reason |
webhook.ping | test | Sent by a webhook test, only to that subscription | webhook_id |
access.rule.created | security | An access rule was added | rule_id, kind, applies_to |
access.rule.deleted | security | An access rule was removed | rule_id, kind, sign_out |
access.sessions.revoked | security | One visitor or every visitor was signed out | sub, all |
access.network_rule.created | security | An IP or country rule was added | rule_id, kind, value, applies_to |
access.network_rule.deleted | security | An IP or country rule was removed | rule_id, kind, value, applies_to |
access.network_mode.updated | security | How network rules combine with sign-in changed | network_mode |
Planned, not yet sent: usage.threshold_reached, analytics.alert.triggered, pii.blocked, token.created, token.revoked.
Choosing events
A subscription lists one or more patterns in event_types:
| Pattern | Matches |
|---|---|
deployment.ready | That type only |
deployment.* | Every type in the family |
* | Every lifecycle and security event — never form.*, hook.*, goal.* or queue.message.dead_lettered |
Data events carry what visitors typed or what another service sent, so they reach only subscriptions that name them. goal.converted is a volume event — one per conversion, with no personal data — and is also sent only to subscriptions that name it.
Edge looks for conversions about once a minute, and only for goals a subscription selects: the goal named in filters.goal_id, or every goal on the subscription's distributions. A conversion is usually delivered within two minutes. Conversions from before the subscription existed are not sent. The event carries the goal, the page, attribution (source, utm_*, country) and a session hash that rotates; never visitor properties, form contents or IP addresses. Subscribing to form.* also needs the form.forward permission and an explicit confirmation; see Send Edge events to a webhook.
Files on form events
When a form takes uploads, form.submitted carries the attached files in data.envelope.files, and form.file.scanned carries one file in data.file:
{
"field": "resume",
"upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B",
"name": "mika-tanaka-cv.pdf",
"type": "application/pdf",
"size": 482113,
"status": "clean",
"reason": null,
"download_url": "https://api.edge.deca-dev.com/v1/file-links/eyJ2IjoxLCJ1Ijoi…"
}reason appears on form.file.scanned: malware, type_mismatch or size_mismatch for a rejected file. On form.submitted a file is usually still scanning.
download_url needs no token; the link is the credential.
| Rule | Value |
|---|---|
| Valid | 7 days from the event's timestamp. Every retry of a delivery carries the same link |
Before the file is clean | 409 not_ready |
| Unknown or expired link | 404 not_found |
| Clean file | 302 to a download valid 60 seconds |
| Audit | Every use is written to the distribution's submission access log |
Treat the link as a secret: anyone holding it can download the file until it expires.
Optional narrowing:
| Field | Effect |
|---|---|
distribution_ids | Only events from these distributions. Omit for the whole workspace |
filters.form_id | form.* only: one form |
filters.hook_slug | hook.* only: one hook |
filters.goal_id | goal.* only: one goal |
Webhook delivery
Edge follows Standard Webhooks, so any of its libraries verifies Edge deliveries.
Body
{
"id": "evt_01JA7Q3M4V9Z0K2H5C8R6T1BXE",
"type": "deployment.ready",
"timestamp": "2026-10-11T03:12:00Z",
"tenant_id": "7c1f9d84-6b20-4e3a-8f57-d94a2e1b6c08",
"namespace_id": "0b8e4a52-31d7-4c9f-9a18-2f6c5d0b7e43",
"distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
"actor": { "kind": "system", "id": "edge" },
"subject": { "kind": "deployment", "id": "01M2QB6JJJS99B7B09VZJ8RST2" },
"data": {
"deployment_id": "01M2QB6JJJS99B7B09VZJ8RST2",
"preview_url": "https://01m2qb6jjjs99b7b09vzj8rst2.preview.edge.deca-dev.com/"
}
}tenant_id is your organization and namespace_id your workspace; the body uses Edge's system names for them. subject.id and distribution_id never change for the thing they name, so they are good keys for grouping related events.
Headers
| Header | Value |
|---|---|
webhook-id | The event id, evt_… |
idempotency-key | The same event id, for receivers that look for this name |
webhook-timestamp | Unix seconds when this attempt was signed |
webhook-signature | v1,<base64> — HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body} with the secret. Two values, space-separated, for 24 hours after a secret rotation |
edge-event-type | The event type |
edge-delivery-attempt | 1 for the first attempt, 2 for the second, … |
content-type | application/json |
user-agent | DECA-Edge-Webhooks/1 |
Rules
| Rule | Value |
|---|---|
| Guarantee | At least once. Retries and redeliveries reuse the same webhook-id, so dedupe on it |
| Ordering | Not guaranteed. Use timestamp, or read the current state from the API |
| Success | Any 2xx |
410 Gone | Turns the subscription off at once |
| Redirects | Not followed; a 3xx is a failed attempt |
| Timeout | 10 seconds per attempt |
| Attempts | 9: immediately, then after waits of 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h, 12 h (the last is about 22.7 h after the first) |
| Auto-disable | After 10 consecutive deliveries fail every attempt. Re-enabling clears the count |
| Secret | whsec_…, shown once at creation and once at rotation |
| URL | https:// only, a public DNS name (no IP address), no credentials, port 443 or 1024 and above. Re-checked at every attempt; private and cloud-metadata addresses are refused |
| Subscriptions | 25 per workspace |
| History | Events, deliveries and attempts are kept 30 days |
Hooks
A hook is a URL on a distribution's own host: https://{slug}.edge.deca-dev.com/_hooks/{hook}, and the same path on any attached custom domain. It works once the distribution has a live deployment. Password protection does not apply to /_hooks; the provider's signature is the authentication.
Presets
| Preset | Verifies | Idempotency key |
|---|---|---|
standard-webhooks | webhook-signature over {webhook-id}.{webhook-timestamp}.{body}, 5-minute tolerance. Secret starts whsec_ | webhook-id |
stripe | Stripe-Signature t=…,v1=… over {t}.{body}, 5-minute tolerance | Body id (evt_…) |
github | X-Hub-Signature-256: sha256=<hex> | X-GitHub-Delivery |
slack | X-Slack-Signature: v0=<hex> over v0:{timestamp}:{body}, 5-minute tolerance. Answers url_verification with the challenge | Body event_id |
line | X-Line-Signature, base64 | The webhookEventId of a single event; for a batch, line: plus the SHA-256 of every events[].webhookEventId joined with commas |
shopify | X-Shopify-Hmac-Sha256, base64 | X-Shopify-Webhook-Id |
hmac | HMAC-SHA256 of the body in a header you name: config.header (default x-signature), config.encoding hex or base64, optional config.prefix | Idempotency-Key header |
token | A secret path segment: /_hooks/{hook}/{token}. Edge generates the token and shows it once | Idempotency-Key header |
Idempotency
Edge picks the key in this order:
- The preset's provider id (table above).
- The
Idempotency-Keyrequest header. sha256(body), only when the hook hasdedupe_body: true.- Otherwise none: every request is new.
The first request with a key creates a receipt and emits hook.received. A later request with the same key on the same hook gets 200, the first receipt_id, "replay": true and the header Edge-Idempotent-Replay: true. It emits nothing and runs no action. Receipts are kept 7 days; look one up by key with edge_hook_receipt_get or GET /v1/distributions/{id}/hooks/{hook_id}/receipts/{key}.
Responses
| Status | Meaning |
|---|---|
200 | Accepted: {"ok": true, "receipt_id", "replay", "idempotency_key"}. Slack verification returns {"challenge"} |
400 | Idempotency key longer than 255 characters |
401 | Signature, token or timestamp check failed. No detail is returned |
404 | No enabled hook with that name on this host, or a token on a signed hook |
405 | Not POST |
413 | Body larger than 256 KB |
Receipt status
| Status | Meaning |
|---|---|
accepted | Stored; the event is waiting to go out |
dispatched | The action is running, or waits to be tried again (result.retrying) |
succeeded | Event sent and action (if any) done. result holds the details |
failed | The action failed. result.error says why |
Actions
config.action | Does |
|---|---|
{"kind": "invalidate", "paths": ["/blog/*"]} | Clears the CDN cache for 1–15 viewer paths |
{"kind": "promote_latest"} | Promotes the newest ready deployment created after the live one. Does nothing if there is none |
{"kind": "enqueue", "queue": "stripe-events"} | Sends one message per request to a queue on the distribution. Needs queue.send |
{"kind": "workflow_start", "script_id": "01J…", "name"?: "onboard"} | Starts a workflow run of that function. Needs workflow.write |
{"kind": "workflow_signal", "run_id_from": "$.data.run_id", "signal": "paid"} | Signals the run whose id is at that path in the payload; the run must be on the distribution. Needs workflow.write |
{"kind": "wasm", "script_id": "01J…"} | Runs that function once per accepted request, after the 200. The function must be on this distribution |
enqueue, workflow_start and workflow_signal pass on {hook, receipt_id, idempotency_key, headers, payload} as the message body, the run's input or the signal's payload, and record message_id, run_id, created or delivered in the receipt's result. Each runs once per accepted request. A full queue, a send rate over its limit, or a distribution at its active-run limit is tried again every 5 minutes for 24 hours (result.retrying). Any other refusal (not_found, too_large, run_finished) fails the receipt. See Buffer webhooks into a queue or a workflow.
wasm posts the hook.received event to /_hooks/{slug} on the request runner. A 2xx marks the receipt succeeded. The receipt's result has status_code, version, duration_ms, and function_event_id. What the function printed is in edge_function_logs with source hook. A worker restart can run it a second time; key the function on data.idempotency_key. See Receive a provider webhook.
invalidate and promote_latest change the live site. Roll back with Promote and roll back if it promoted the wrong deployment.
| Limit | Value |
|---|---|
| Hooks per distribution | 20 |
| Body | 256 KB |
| Rate | 600 requests per 5 minutes per client IP across /_hooks |
Subscribing to form.* also requires form.forward. {hook_id} accepts the hook's id or its name.
Routes, tools, and commands are listed by scope on their own pages:
- HTTP API — each route and the scope it requires
- MCP — each tool and the scope it requires
- CLI — each command and the scope it requires