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.
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.
Grouping related events
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.