Skip to content

Events and webhooks ​

Edge records an event every time something changes: a deployment becomes ready, a domain verifies, a visitor submits a form, another service calls a hook. Webhooks carry those events out of Edge; hooks bring other services' events in.

Deploy, domain, formstate changes in EdgePOST /_hooks/stripeverified, deduplicatedEventevt_… saved with the changeYour endpointchecks webhook-signaturesame commithook.receivedsigned, retried
An event is saved together with the change it describes, then delivered to every matching webhook, signed and retried.

An event is saved with the change ​

Edge writes the event in the same database transaction as the change itself. If the deployment became ready, the deployment.ready event exists; if the write failed, neither exists. Nothing is announced that did not happen, and nothing that happened goes unannounced because a process stopped at the wrong moment.

Delivery is at least once ​

Networks fail in the middle: your endpoint may process an event and the reply may never arrive. Edge then sends it again. So delivery is at least once, not exactly once, and every retry carries the same webhook-id. A receiver that records the ids it has handled gets exactly-once processing on top of at-least-once delivery. That is the contract almost every webhook system offers, and the one Standard Webhooks — the format Edge uses — is built around.

Edge does not promise order either. A deployment.promoted can arrive before the deployment.ready that preceded it if the first attempt of ready failed. Use the timestamp, or treat the event as a prompt to read the current state from the API.

Hooks deduplicate retries for you ​

Inbound, the roles reverse: Stripe, GitHub or LINE retry, and Edge is the receiver. Each hook keeps a receipt per idempotency key, claimed before anything else runs, so two copies of the same event arriving at once cannot both get through. The repeat is answered 200 — the sender sees success and stops retrying — and nothing is emitted or promoted a second time.

Why form data needs an extra yes ​

Most events describe Edge itself. form.submitted and hook.received carry what other people sent: names, emails, order details. Those are data events:

  • * never includes them, so a broad subscription cannot leak them by accident.
  • Forwarding form submissions needs form.forward, which only admins have, plus an explicit confirmation. Edge's agent tools cannot read form submissions at all; a webhook is the one way they leave Edge, so creating one is treated as the decision it is.

Conversions arrive a minute later ​

goal.converted works differently from every other event. A conversion is not a change in Edge; it is a visit that matches a goal's rule, and those rules are evaluated over the analytics data. So Edge looks for new conversions about once a minute, and only for goals that a subscription selects — a goal nobody subscribes to costs nothing. Each conversion has a fixed event id, so looking twice never sends it twice. Like data events, * leaves it out: there is one per conversion, and a busy site would otherwise flood a receiver that only wanted deploy notices.

Each event's subject.id names the thing it is about — one deployment, one submission, one hook receipt — and distribution_id names the site. A receiver such as an agent platform can keep one conversation per submission or per site by keying on them.

See also ​