Skip to content

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 ​

TypeClassSent whendata fields
deployment.createdlifecycleA deployment was created, including by a rollbackdeployment_id, from_deployment_id
deployment.readylifecycleThe preview is publisheddeployment_id, preview_url
deployment.failedlifecycleThe deployment could not be publisheddeployment_id
deployment.promotedlifecycleThe live site moved to this deploymentdeployment_id, previous_deployment_id, schedule_id (when a schedule promoted it)
deployment.scheduledlifecycleA promote, takedown or restore was scheduledschedule_id, action, deployment_id, run_at
deployment.schedule_cancelledlifecycleA pending schedule was cancelledschedule_id, action, deployment_id, run_at
deployment.schedule_failedlifecycleA schedule could not run: its deployment was not ready, it was more than a day late, or an errorschedule_id, action, deployment_id, run_at, error
distribution.createdlifecycleA distribution was createdslug
distribution.updatedlifecycleDistribution settings changedchanges — the top-level setting names that differ
distribution.taken_downlifecycleLive hosts now answer 410 Gone or a temporary redirectmode, location, schedule_id
distribution.restoredlifecycleA takedown was liftedschedule_id
distribution.destroyedlifecycleA distribution was deletedslug
domain.verifiedlifecycleDomain ownership was verifiedfqdn, status
domain.activelifecycleThe domain serves traffic with a certificatefqdn, status
domain.failedlifecycleVerification or provisioning failedfqdn, status
domain.attachedlifecycleThe domain was attached to a distributionfqdn
domain.detachedlifecycleThe domain was detachedfqdn
function.build.succeededlifecycleA function runtime build published a new versionscript_id, version
function.build.failedlifecycleA function runtime build failedscript_id
cron.firedlifecycleA cron with the emit target ran (one event per run)job_id, attempt, owner_kind, owner_id, scheduled_for
cron.run.failedlifecycleA cron run failed and has no retries leftcron_id, name, job_id, attempt, error_code
cron.run.missedlifecycleA cron slot was reached more than a day late and was not runcron_id, name, job_id, scheduled_for
queue.backlog.highlifecycleA 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_lettereddataA queue message used its last attempt and is now deadqueue_id, name, message_id, attempts, error, job_id, body
workflow.completedlifecycleA workflow run's step answered donerun_id, name, script_id, step
workflow.failedlifecycleA workflow run failed: a step answered fail, ran out of retries, timed out waiting with no timeout step, or the run expiredrun_id, name, script_id, step, error, error_code
form.submitteddata/_submit stored a form submissionform_id, submission_id, path, envelope (with files when the form takes uploads)
form.file.scanneddataA file attached to a submission finished its scan: clean, rejected or scan_failed. Sent once per fileform_id, submission_id, file
hook.receiveddataA hook accepted a verified requesthook_id, hook_slug, preset, receipt_id, idempotency_key, key_source, headers, payload
goal.convertedvolumeA human visit matched a conversion goal a subscription selectsgoal_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.createdsecurityA webhook subscription was createdwebhook_id, url_host, event_types
webhook.subscription.disabledsecurityA subscription was turned off after repeated failureswebhook_id, url_host, reason
webhook.pingtestSent by a webhook test, only to that subscriptionwebhook_id
access.rule.createdsecurityAn access rule was addedrule_id, kind, applies_to
access.rule.deletedsecurityAn access rule was removedrule_id, kind, sign_out
access.sessions.revokedsecurityOne visitor or every visitor was signed outsub, all
access.network_rule.createdsecurityAn IP or country rule was addedrule_id, kind, value, applies_to
access.network_rule.deletedsecurityAn IP or country rule was removedrule_id, kind, value, applies_to
access.network_mode.updatedsecurityHow network rules combine with sign-in changednetwork_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:

PatternMatches
deployment.readyThat 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:

json
{
  "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.

RuleValue
Valid7 days from the event's timestamp. Every retry of a delivery carries the same link
Before the file is clean409 not_ready
Unknown or expired link404 not_found
Clean file302 to a download valid 60 seconds
AuditEvery 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:

FieldEffect
distribution_idsOnly events from these distributions. Omit for the whole workspace
filters.form_idform.* only: one form
filters.hook_slughook.* only: one hook
filters.goal_idgoal.* only: one goal

Webhook delivery ​

Edge follows Standard Webhooks, so any of its libraries verifies Edge deliveries.

Body

json
{
  "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

HeaderValue
webhook-idThe event id, evt_…
idempotency-keyThe same event id, for receivers that look for this name
webhook-timestampUnix seconds when this attempt was signed
webhook-signaturev1,<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-typeThe event type
edge-delivery-attempt1 for the first attempt, 2 for the second, …
content-typeapplication/json
user-agentDECA-Edge-Webhooks/1

Rules

RuleValue
GuaranteeAt least once. Retries and redeliveries reuse the same webhook-id, so dedupe on it
OrderingNot guaranteed. Use timestamp, or read the current state from the API
SuccessAny 2xx
410 GoneTurns the subscription off at once
RedirectsNot followed; a 3xx is a failed attempt
Timeout10 seconds per attempt
Attempts9: 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-disableAfter 10 consecutive deliveries fail every attempt. Re-enabling clears the count
Secretwhsec_…, shown once at creation and once at rotation
URLhttps:// 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
Subscriptions25 per workspace
HistoryEvents, 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 ​

PresetVerifiesIdempotency key
standard-webhookswebhook-signature over {webhook-id}.{webhook-timestamp}.{body}, 5-minute tolerance. Secret starts whsec_webhook-id
stripeStripe-Signature t=…,v1=… over {t}.{body}, 5-minute toleranceBody id (evt_…)
githubX-Hub-Signature-256: sha256=<hex>X-GitHub-Delivery
slackX-Slack-Signature: v0=<hex> over v0:{timestamp}:{body}, 5-minute tolerance. Answers url_verification with the challengeBody event_id
lineX-Line-Signature, base64The webhookEventId of a single event; for a batch, line: plus the SHA-256 of every events[].webhookEventId joined with commas
shopifyX-Shopify-Hmac-Sha256, base64X-Shopify-Webhook-Id
hmacHMAC-SHA256 of the body in a header you name: config.header (default x-signature), config.encoding hex or base64, optional config.prefixIdempotency-Key header
tokenA secret path segment: /_hooks/{hook}/{token}. Edge generates the token and shows it onceIdempotency-Key header

Idempotency ​

Edge picks the key in this order:

  1. The preset's provider id (table above).
  2. The Idempotency-Key request header.
  3. sha256(body), only when the hook has dedupe_body: true.
  4. 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 ​

StatusMeaning
200Accepted: {"ok": true, "receipt_id", "replay", "idempotency_key"}. Slack verification returns {"challenge"}
400Idempotency key longer than 255 characters
401Signature, token or timestamp check failed. No detail is returned
404No enabled hook with that name on this host, or a token on a signed hook
405Not POST
413Body larger than 256 KB

Receipt status ​

StatusMeaning
acceptedStored; the event is waiting to go out
dispatchedThe action is running, or waits to be tried again (result.retrying)
succeededEvent sent and action (if any) done. result holds the details
failedThe action failed. result.error says why

Actions ​

config.actionDoes
{"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.

LimitValue
Hooks per distribution20
Body256 KB
Rate600 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

See also ​