Skip to content

Send Edge events to a webhook ​

A webhook subscription makes Edge POST a signed JSON event to your endpoint whenever something happens — a preview is ready, a deployment goes live, a form is submitted. Creating one does not change any distribution or the live site.

The web app does not manage webhooks yet. Use an agent, the CLI, or the API.

1. Create the subscription ​

text
Send deployment events from acme-marketing to https://hooks.acme.example/edge.
bash
edge webhooks create \
  --url https://hooks.acme.example/edge \
  --event deployment.* \
  --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 \
  --description "Deploy notifications"
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/webhooks \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://hooks.acme.example/edge",
        "event_types": ["deployment.*"],
        "distribution_ids": ["d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38"],
        "description": "Deploy notifications"
      }'

The agent runs edge_webhook_create. The response includes the signing secret:

json
{
  "webhook_id": "wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39",
  "url": "https://hooks.acme.example/edge",
  "event_types": ["deployment.*"],
  "enabled": true,
  "secret": "whsec_kQ3m8yQx2v0bN6pT1rL5sW9eHcJ4uA7d",
  "secret_shown_once": true,
  …
}

Store secret now. Edge never shows it again; if you lose it, rotate it (step 5).

Omit distribution_ids to receive events from every distribution in the workspace. Use ["*"] for every lifecycle event. The full list is in Events, webhooks, and hooks.

2. Verify the signature in your receiver ​

Edge signs with Standard Webhooks. Use its library for your language, or check it by hand:

js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, headers, secret) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const expected = 'v1,' + createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest('base64');
  return headers['webhook-signature'].split(' ').some(
    (candidate) => candidate.length === expected.length && timingSafeEqual(Buffer.from(candidate), Buffer.from(expected)),
  );
}

Verify against the raw request body, before any JSON parsing.

Edge delivers at least once. Store webhook-id (also sent as Idempotency-Key) and skip an id you have already processed. Answer with any 2xx within 10 seconds and do the slow work afterwards.

3. Send a test event ​

text
Test the deploy-notifications webhook.
bash
edge webhooks test wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/webhooks/wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39/test \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_webhook_test. Edge sends one webhook.ping right away and returns what your endpoint answered:

json
{ "ok": true, "status_code": 204, "response_excerpt": null, "duration_ms": 182, … }

A failed test is not retried and does not count towards turning the subscription off.

4. Check deliveries ​

text
Show the last deliveries for the deploy-notifications webhook.
bash
edge webhooks deliveries wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39 --limit 10
bash
curl -s https://api.edge.deca-dev.com/v1/webhooks/wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39/deliveries?limit=10 \
  -H "Authorization: Bearer $EDGE_TOKEN"

Each delivery shows its status (pending, succeeded, failed, cancelled) and every attempt with its status code and error. A failed attempt is retried for about 22 hours. To send one again — for example after fixing a bug in your receiver — redeliver it (edge webhooks redeliver, or ask your agent to run edge_webhook_redeliver). The redelivery carries the same webhook-id, so a receiver that already handled it can skip it.

After 10 deliveries in a row fail, Edge turns the subscription off and records disabled_reason. Fix the endpoint, then turn it back on with edge webhooks update wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39 --enabled true (the agent runs edge_webhook_update).

5. Rotate the secret ​

text
Rotate the signing secret of the deploy-notifications webhook.
bash
edge webhooks rotate-secret wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/webhooks/wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39/rotate-secret \
  -H "Authorization: Bearer $EDGE_TOKEN"

The new secret is shown once. For 24 hours each delivery carries two signatures, one per secret, so you can switch the receiver without missing events.

Forward form submissions ​

form.submitted carries what a visitor typed into your form. It is never included in *, and subscribing to it needs the form.forward permission, which only workspace admins have.

Edge also asks for confirmation. The first request returns a summary and creates nothing:

json
{
  "status": "confirmation_required",
  "summary": "This subscription sends every matching form submission, including what visitors typed, to crm.acme.example. …",
  "url_host": "crm.acme.example"
}

An agent must show you that summary and wait for your yes. It then repeats the request with "confirm": true. Changing the URL, the event types or the distributions of a form subscription needs the same permission and confirmation; turning it off does not.

text
Forward contact-form submissions from acme-marketing to https://crm.acme.example/edge-leads.
bash
edge webhooks create \
  --url https://crm.acme.example/edge-leads \
  --event form.submitted \
  --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 \
  --filters - --yes <<'EOF'
{"form_id": "contact"}
EOF
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/webhooks \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://crm.acme.example/edge-leads",
        "event_types": ["form.submitted"],
        "distribution_ids": ["d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38"],
        "filters": { "form_id": "contact" },
        "confirm": true
      }'

Each event's data.envelope is the submission exactly as Edge stored it.

Send goal conversions ​

goal.converted sends one event each time a human visit matches a conversion goal — for example to report sign-ups to an ad platform or a CRM. It is never part of *; name it, and narrow it to one goal with filters.goal_id.

text
Send sign-up goal conversions from acme-marketing to https://ads.acme.example/edge-conversions.
bash
edge webhooks create \
  --url https://ads.acme.example/edge-conversions \
  --event goal.converted \
  --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 \
  --filters - <<'EOF'
{"goal_id": "5e0b7a92-3c1d-4f6e-9a8b-2d4c6e8f0a13"}
EOF
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/webhooks \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://ads.acme.example/edge-conversions",
        "event_types": ["goal.converted"],
        "distribution_ids": ["d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38"],
        "filters": { "goal_id": "5e0b7a92-3c1d-4f6e-9a8b-2d4c6e8f0a13" }
      }'

Edge checks for new conversions about once a minute, so expect each one within about two minutes. Only conversions after the subscription exists are sent. Each event carries the goal, the page, the visit's attribution (source, utm_*, country) and a session hash; it never carries visitor properties or form contents, so no extra permission is needed. Bot traffic is not counted, matching the conversion numbers in the web app.

Next ​