Skip to content

Edge のイベントを Webhook に送る ​

Webhook サブスクリプションを作成すると、プレビューの準備完了、deployment の本番反映、 フォームの送信など、何かが起きるたびに Edge が署名付きの JSON イベントをエンドポイントへ POST します。作成しても distribution や本番サイトは変わりません。

web app ではまだ Webhook を管理できません。エージェント、CLI、または API を使用します。

1. サブスクリプションを作成する ​

text
acme-marketing の deployment イベントを 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"
      }'

エージェントは edge_webhook_create を実行します。レスポンスには署名用シークレットが含まれます。

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

secret はこの時点で保存してください。 Edge が再び表示することはありません。紛失した 場合はローテーションします(手順 5)。

distribution_ids を省略すると、ワークスペース内のすべての distribution のイベントを 受け取ります。すべてのライフサイクルイベントを受け取るには ["*"] を使います。一覧は イベント、Webhook、フック にあります。

2. 受信側で署名を検証する ​

Edge は Standard Webhooks 形式で署名します。 お使いの言語向けのライブラリを使うか、次のように自分で検証します。

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)),
  );
}

検証は JSON を解析する前の 生の リクエストボディに対して行ってください。

Edge の配信は at least once(少なくとも 1 回) です。webhook-id(Idempotency-Key としても送られます)を保存し、処理済みの id はスキップしてください。10 秒以内に任意の 2xx で応答し、時間のかかる処理はそのあとで行います。

3. テストイベントを送る ​

text
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"

エージェントは edge_webhook_test を実行します。Edge はただちに webhook.ping を 1 件 送り、エンドポイントの応答を返します。

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

失敗したテストは再試行されず、サブスクリプションを無効化するまでの失敗回数にも数えられません。

4. 配信状況を確認する ​

text
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"

各配信には status(pending、succeeded、failed、cancelled)と、試行ごとの ステータスコードとエラーが表示されます。失敗した試行は約 22 時間にわたって再試行されます。 受信側のバグを直したあとなどにもう一度送るには、edge webhooks redeliver を実行するか、 エージェントに再配信を依頼します(edge_webhook_redeliver)。再配信は 同じ webhook-id を持つため、処理済みの受信側は スキップできます。

配信が 10 回連続で失敗すると、Edge はサブスクリプションを無効にし、disabled_reason を 記録します。エンドポイントを修正したら、 edge webhooks update wh_5f0c2a7e9b3d4e1fa6c8b2d0e4f71a39 --enabled true で再び有効にします(エージェントは edge_webhook_update を実行します)。

5. シークレットをローテーションする ​

text
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"

新しいシークレットは一度だけ表示されます。24 時間のあいだ、各配信には新旧それぞれの シークレットによる 2 つの署名が付くため、イベントを取りこぼさずに受信側を切り替えられます。

フォームの送信を転送する ​

form.submitted には、訪問者がフォームに入力した内容が含まれます。このイベントは * に 含まれることはなく、購読するにはワークスペースの admin だけが持つ form.forward 権限が 必要です。

Edge は確認も求めます。最初のリクエストは概要を返すだけで、何も作成しません。

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"
}

エージェントはこの概要をあなたに示し、承認を待つ必要があります。承認後、 "confirm": true を付けて同じリクエストを送り直します。フォームのサブスクリプションの URL、 イベントタイプ、distribution を変更する場合も同じ権限と確認が必要です。無効にする場合は 不要です。

text
acme-marketing のお問い合わせフォームの送信内容を 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
      }'

各イベントの data.envelope は、Edge が保存したとおりの送信内容です。

ゴールのコンバージョンを送る ​

goal.converted は、人間の訪問がコンバージョンゴールに一致するたびにイベントを ひとつ送ります。たとえば、登録数を広告プラットフォームや CRM に報告するときに使います。* には 決して含まれないので明示的に指定し、filters.goal_id でひとつのゴールに絞り込みます。

text
acme-marketing の登録ゴールのコンバージョンを 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 はおよそ 1 分ごとに新しいコンバージョンを確認するため、各イベントは約 2 分以内に届きます。 送られるのはサブスクリプション作成後のコンバージョンだけです。各イベントにはゴール、ページ、訪問の 流入元(source、utm_*、country)とセッションハッシュが含まれます。訪問者のプロパティや フォームの内容は決して含まれないため、追加の権限は必要ありません。ボットのトラフィックは数えられず、 Web アプリのコンバージョン数と一致します。

次のステップ ​