他サービスの Webhook を受け取る
フックは distribution 上の URL(https://acme-marketing.edge.deca-dev.com/_hooks/stripe) で、他のサービスからの Webhook を受け付けます。Edge は送信元の署名を検証し、同じイベントの 再送を無視して、受け付けた各リクエストを hook.received イベントに変換します。このイベントは 転送したり、アクションのきっかけにしたりできます。
フックを作成しても本番サイトは変わりません。フックが応答するのは、distribution に live deployment がある場合だけです。web app ではまだフックを管理できないため、エージェント、CLI、または API を使用します。
1. フックを作成する
送信元に合ったプリセットを選びます。シークレットは送信元から渡されたものです。
acme-marketing に stripe という名前の Stripe Webhook 受信先を追加してください。署名用シークレットは whsec_8Qp… です。edge hooks create acme-marketing --slug stripe --preset stripe --secret 'whsec_8Qp…'curl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "slug": "stripe", "preset": "stripe", "secret": "whsec_8Qp…" }'エージェントは edge_hook_create を実行します。レスポンスには送信元に渡す URL が含まれます。
{
"hook_id": "hk_2b9e4c1d7a0f4e6b8c3d5a1f9e7b0c42",
"slug": "stripe",
"preset": "stripe",
"url": "https://acme-marketing.edge.deca-dev.com/_hooks/stripe",
"enabled": true,
…
}Edge はシークレットを暗号化して保存し、返すことはありません。プリセットは standard-webhooks、stripe、github、slack、line、shopify、hmac、token です。 プリセット を参照してください。
署名できない送信元(CI ジョブ、cron、ノーコードツールなど)には token プリセットを 使います。Edge が秘密のパスセグメントを生成し、完全な URL を一度だけ表示します。
{ "url": "https://acme-marketing.edge.deca-dev.com/_hooks/ci/vQ0m3Lr9…", "token_shown_once": true, … }2. 送信元に URL を設定する
URL を送信元の Webhook 設定(Stripe ダッシュボード、GitHub リポジトリの設定、LINE Developers コンソールなど)に貼り付け、そこからテストイベントを送ります。Slack の URL 検証には自動で 応答します。
3. 届いた内容を確認する
acme-marketing の stripe フックの直近の受信記録を表示してください。edge hooks receipts acme-marketing hk_2b9e4c1d7a0f4e6b8c3d5a1f9e7b0c42curl -s https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/stripe/receipts \
-H "Authorization: Bearer $EDGE_TOKEN"[
{
"receipt_id": "rcpt_9a1f0e…",
"idempotency_key": "evt_1QhZ3k2eZvKYlo2C",
"key_source": "provider",
"status": "succeeded",
"received_at": "2026-10-11T03:20:11Z",
…
}
]署名の検証で拒否されたリクエストには 401 が返り、受信記録(receipt)は残りません。何も 表示されない場合は、シークレットと、distribution が公開中であることを確認してください。
重複と冪等キー
送信元は再送します。Edge は 冪等キー によって再送を見分けます。プリセットに送信元自身の イベント id がある場合はそれ(Stripe の evt_…、GitHub の delivery id)、無い場合は Idempotency-Key ヘッダーです。あるキーを持つ最初のリクエストが処理されます。再送には 200 と "replay": true、元の receipt_id、Edge-Idempotent-Replay: true が返り、何も 二重に実行されません。
自分でリクエストを送る場合は、キーを含めてください。
curl -s -X POST https://acme-marketing.edge.deca-dev.com/_hooks/ci/vQ0m3Lr9… \
-H "Idempotency-Key: build-1842" \
-H "Content-Type: application/json" \
-d '{"ref": "main", "status": "passed"}'Edge がそのキーをすでに受け取っているかを確認するには、 edge hooks receipt acme-marketing hk_2b9e4c1d7a0f4e6b8c3d5a1f9e7b0c42 build-1842 を実行する(エージェントは edge_hook_receipt_get を実行します)か、 GET /v1/distributions/{id}/hooks/{hook}/receipts/build-1842 を呼び出します。"found": false は、直近 7 日間に Edge がそのキーを受け取っていないことを 意味します。
Webhook を受けてキャッシュをクリアする、または promote する
フックは distribution に対してアクションを実行することもできます。これは本番サイトを変更します。 フックに設定できるアクションは 1 つだけです(キャッシュのクリア、promote、または次の節の関数ランタイム)。
- CMS が公開したときに キャッシュをクリアする:
"config": {"action": {"kind": "invalidate", "paths": ["/blog/*"]}} - CI が通ったときに 最新の ready deployment を promote する:
"config": {"action": {"kind": "promote_latest"}}
acme-marketing の ci フックで、最新の ready deployment を promote するようにしてください。edge hooks update acme-marketing ci --config - <<'EOF'
{"action": {"kind": "promote_latest"}}
EOFcurl -s -X PATCH \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/ci \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "config": { "action": { "kind": "promote_latest" } } }'受信記録の result に結果が表示されます。たとえば {"promoted": "01M2QB6J…"}、promote する 新しいものが無かった場合は {"promoted": null} です。promote を取り消すには パッチ、公開、切り戻し を参照してください。
Webhook を受けて関数ランタイムを実行する
フックは、受け付けたリクエストごとに distribution の関数ランタイムを実行することもできます。 Edge が先に署名を検証し重複を除くため、コードには検証済みの新しいイベントだけが届きます。 先に関数ランタイムをビルドし、フックにその script_id を指定します。
"config": {"action": {"kind": "wasm", "script_id": "01JB7Q2M5V8K3N6P9R1T4W7Y0Z"}}
acme-marketing の stripe フックで、イベントごとに order-sync 関数を実行するようにしてください。edge hooks update acme-marketing stripe --config - <<'EOF'
{"action": {"kind": "wasm", "script_id": "01JB7Q2M5V8K3N6P9R1T4W7Y0Z"}}
EOFcurl -s -X PATCH \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/stripe \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "config": { "action": { "kind": "wasm", "script_id": "01JB7Q2M5V8K3N6P9R1T4W7Y0Z" } } }'関数ランタイムは同じ distribution のものである必要があります。コードには /_hooks/{名前} への POST が届き、ボディは hook.received イベントです。これは hook.* を購読した Webhook が 受け取る JSON と同じです。送信元のペイロードは data.payload、一部のヘッダーは data.headers、Edge が重複判定に使ったキーは data.idempotency_key に入ります。関数は 直接 invoke と同じドキュメント、ファイル、ストアの権限を持ちます。
{
"id": "evt_01JB7R…",
"type": "hook.received",
"distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
"data": {
"hook_slug": "stripe",
"idempotency_key": "evt_1QhZ3k2eZvKYlo2C",
"payload": { "id": "evt_1QhZ3k2eZvKYlo2C", "type": "checkout.session.completed", … }
},
…
}コードは Edge が送信元に 200 を返した後に実行されるため、そのレスポンスは送信元には 返りません。2xx なら受信記録は succeeded、それ以外は failed になります。受信記録の result には status_code、実行された version、function_event_id が入ります。 コードの出力は関数ランタイムのログ(edge_function_logs)に、そのイベント ID と source: "hook" で記録されます。
Edge は冪等キーごとに 1 回コードを実行します。実行中にワーカーが再起動すると 2 回目が 実行されることがあるため、data.idempotency_key を使って繰り返し実行しても安全なコードに してください。
キューに入れる、またはワークフローを開始する
フックは各リクエストをキューに入れたり、ワークフロー実行を開始したり、待機中の実行を再開したりもできます。Webhook をキューやワークフローに受け渡す を参照してください。
ペイロードを転送する
受け付けたリクエストはすべて、ペイロードを含む hook.received を発行します。これをエージェント プラットフォーム、キュー、バックエンドなどに渡すには、Webhook で hook.* を購読します。 必要に応じて "filters": {"hook_slug": "stripe"} で絞り込めます。 Edge のイベントを Webhook に送る を参照してください。Edge は 送信元の署名を一度だけ検証し、転送するイベントには Edge 自身の署名を付けます。