Skip to content

イベント、Webhook、フック ​

Webhook は Edge のイベントを HTTPS エンドポイントに送ります。フック は https://{slug}.edge.deca-dev.com/_hooks/{hook} で他サービスからの Webhook を受け取ります。 どちらもエージェントまたは HTTP API で設定します。web app ではまだ管理できません。エージェントは 同じ情報を MCP リソース edge://webhooks から読み取れます。

全体の関係は イベントと Webhook を、ホストについては 環境とドメイン を参照してください。

イベントタイプ ​

タイプ分類送信されるタイミングdata のフィールド
deployment.createdlifecycledeployment が作成された(rollback によるものを含む)deployment_id, from_deployment_id
deployment.readylifecycleプレビューが公開されたdeployment_id, preview_url
deployment.failedlifecycledeployment を公開できなかったdeployment_id
deployment.promotedlifecycle本番サイトがこの deployment に切り替わったdeployment_id, previous_deployment_id, schedule_id(予約によって promote された場合)
deployment.scheduledlifecyclepromote、公開停止、復元が予約されたschedule_id, action, deployment_id, run_at
deployment.schedule_cancelledlifecycle未実行の予約が取り消されたschedule_id, action, deployment_id, run_at
deployment.schedule_failedlifecycle予約を実行できなかった。deployment が ready でない、1 日以上遅れた、またはエラーschedule_id, action, deployment_id, run_at, error
distribution.createdlifecycledistribution が作成されたslug
distribution.updatedlifecycledistribution の設定が変更されたchanges — 差分のあるトップレベルの設定名
distribution.taken_downlifecycle公開中のホストが 410 Gone または一時的なリダイレクトを返すようになったmode, location, schedule_id
distribution.restoredlifecycle公開停止が解除されたschedule_id
distribution.destroyedlifecycledistribution が削除されたslug
domain.verifiedlifecycleドメインの所有権が検証されたfqdn, status
domain.activelifecycleドメインが証明書付きでトラフィックを配信しているfqdn, status
domain.failedlifecycle検証またはプロビジョニングが失敗したfqdn, status
domain.attachedlifecycleドメインが distribution に割り当てられたfqdn
domain.detachedlifecycleドメインの割り当てが解除されたfqdn
function.build.succeededlifecycle関数ランタイムのビルドが新しいバージョンを公開したscript_id, version
function.build.failedlifecycle関数ランタイムのビルドが失敗したscript_id
cron.firedlifecycleemit ターゲットの cron が実行された(実行ごとに 1 件)job_id, attempt, owner_kind, owner_id, scheduled_for
cron.run.failedlifecyclecron の実行が失敗し、再試行も残っていないcron_id, name, job_id, attempt, error_code
cron.run.missedlifecyclecron の実行時刻に 1 日以上遅れて到達したため実行しなかったcron_id, name, job_id, scheduled_for
workflow.completedlifecycleワークフローの実行のステップが done を返したrun_id, name, script_id, step
workflow.failedlifecycleワークフローの実行が失敗した。ステップが fail を返した、再試行を使い切った、タイムアウト用のステップなしで待ちがタイムアウトした、または実行の寿命が過ぎたrun_id, name, script_id, step, error, error_code
queue.backlog.highlifecycleキューに 10,000 件を超えるメッセージがある、またはいちばん古いメッセージが 1 時間以上待っている(キューごとに 1 時間に 1 回まで)queue_id, name, depth, oldest_ready_age_seconds, depth_threshold, age_threshold_seconds
queue.message.dead_lettereddataキューのメッセージが最後の試行を使い切り dead になったqueue_id, name, message_id, attempts, error, job_id, body
form.submitteddata/_submit がフォームの送信を保存したform_id, submission_id, path, envelope(フォームがアップロードを受け付ける場合は files 付き)
form.file.scanneddata送信に添付されたファイルのスキャンが clean、rejected、scan_failed のいずれかで終わった。ファイルごとに 1 回form_id, submission_id, file
hook.receiveddataフックが検証済みのリクエストを受け付けたhook_id, hook_slug, preset, receipt_id, idempotency_key, key_source, headers, payload
goal.convertedvolumeサブスクリプションが選んだコンバージョンゴールに人間の訪問が一致したgoal_id, goal_slug, goal_type, analytics_event_id, session_hash, path, event_name, source, utm_source, utm_medium, utm_campaign, country, deployment_id, converted_at
webhook.subscription.createdsecurityWebhook サブスクリプションが作成されたwebhook_id, url_host, event_types
webhook.subscription.disabledsecurity失敗が続いたためサブスクリプションが無効になったwebhook_id, url_host, reason
webhook.pingtestWebhook のテストで、そのサブスクリプションにだけ送られるwebhook_id
access.rule.createdsecurityアクセスルールが追加されたrule_id, kind, applies_to
access.rule.deletedsecurityアクセスルールが削除されたrule_id, kind, sign_out
access.sessions.revokedsecurity1 人、または全員がサインアウトされたsub, all
access.network_rule.createdsecurityIP または国のルールが追加されたrule_id, kind, value, applies_to
access.network_rule.deletedsecurityIP または国のルールが削除されたrule_id, kind, value, applies_to
access.network_mode.updatedsecurityネットワークルールとサインインの組み合わせ方が変わったnetwork_mode

予定されているが、まだ送信されないもの: usage.threshold_reached、 analytics.alert.triggered、pii.blocked、token.created、token.revoked。

イベントの選び方 ​

サブスクリプションは event_types にひとつ以上のパターンを指定します。

パターン一致するもの
deployment.readyそのタイプだけ
deployment.*そのファミリーのすべてのタイプ
*すべての lifecycle イベントと security イベント。form.*、hook.*、goal.*、queue.message.dead_lettered は 決して 含まない

データイベントは訪問者が入力した内容や他サービスが送った内容を運ぶため、それを明示的に指定した サブスクリプションにだけ届きます。form.* を購読するには、さらに form.forward 権限と明示的な 確認が必要です。 Edge のイベントを Webhook に送る を参照してください。

goal.converted は volume イベントです。コンバージョンごとにひとつ送られ、個人データは 含みません。これも、明示的に指定したサブスクリプションにだけ届きます。

Edge はおよそ 1 分ごとに、サブスクリプションが選んだゴールについてだけコンバージョンを探します。 対象は filters.goal_id で指定したゴール、または指定がなければサブスクリプションの distribution の すべてのゴールです。コンバージョンは通常 2 分以内に配信されます。サブスクリプションを作る前の コンバージョンは送られません。イベントにはゴール、ページ、流入元(source、utm_*、country)と ローテーションするセッションハッシュが含まれ、訪問者のプロパティ、フォームの内容、IP アドレスは 決して含まれません。

フォームのイベントのファイル ​

フォームが アップロード を受け付ける場合、form.submitted は添付ファイルを data.envelope.files に、form.file.scanned は 1 つのファイルを data.file に含めます。

json
{
  "field": "resume",
  "upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B",
  "name": "mika-tanaka-cv.pdf",
  "type": "application/pdf",
  "size": 482113,
  "status": "clean",
  "reason": null,
  "download_url": "https://api.edge.deca-dev.com/v1/file-links/eyJ2IjoxLCJ1Ijoi…"
}

reason は form.file.scanned に入ります。rejected のファイルでは malware、type_mismatch、size_mismatch のいずれかです。form.submitted の時点では、ファイルはたいてい scanning です。

download_url にトークンは不要です。リンクそのものが資格情報です。

規則値
有効期間イベントの timestamp から 7 日。同じ配信の再試行には同じリンクが入る
ファイルが clean になる前409 not_ready
不明または期限切れのリンク404 not_found
clean のファイル60 秒有効なダウンロードへ 302
監査使用のたびに distribution の送信内容アクセスログに書かれる

リンクはシークレットとして扱ってください。リンクを持っている人は、期限まで誰でもファイルをダウンロードできます。

任意の絞り込み:

フィールド効果
distribution_idsこれらの distribution のイベントだけ。省略するとワークスペース全体
filters.form_idform.* のみ: ひとつのフォーム
filters.hook_slughook.* のみ: ひとつのフック
filters.goal_idgoal.* のみ: ひとつのゴール

Webhook の配信 ​

Edge は Standard Webhooks に従っているため、そのライブラリの どれでも Edge からの配信を検証できます。

ボディ

json
{
  "id": "evt_01JA7Q3M4V9Z0K2H5C8R6T1BXE",
  "type": "deployment.ready",
  "timestamp": "2026-10-11T03:12:00Z",
  "tenant_id": "7c1f9d84-6b20-4e3a-8f57-d94a2e1b6c08",
  "namespace_id": "0b8e4a52-31d7-4c9f-9a18-2f6c5d0b7e43",
  "distribution_id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
  "actor": { "kind": "system", "id": "edge" },
  "subject": { "kind": "deployment", "id": "01M2QB6JJJS99B7B09VZJ8RST2" },
  "data": {
    "deployment_id": "01M2QB6JJJS99B7B09VZJ8RST2",
    "preview_url": "https://01m2qb6jjjs99b7b09vzj8rst2.preview.edge.deca-dev.com/"
  }
}

tenant_id は組織、namespace_id はワークスペースです。本文では Edge のシステム上の名前を使います。 subject.id と distribution_id は、それが示す対象について変わることがないため、関連する イベントをまとめるキーに適しています。

ヘッダー

ヘッダー値
webhook-idイベント id(evt_…)
idempotency-key同じイベント id。この名前を参照する受信側のため
webhook-timestampこの試行が署名された時刻(Unix 秒)
webhook-signaturev1,<base64> — {webhook-id}.{webhook-timestamp}.{body} をシークレットで HMAC-SHA256 したもの。シークレットのローテーション後 24 時間は、スペース区切りで 2 つの値
edge-event-typeイベントタイプ
edge-delivery-attempt最初の試行は 1、2 回目は 2、…
content-typeapplication/json
user-agentDECA-Edge-Webhooks/1

ルール

ルール値
保証at least once。再試行と再配信は同じ webhook-id を使うので、それで重複を除く
順序保証しない。timestamp を使うか、API から現在の状態を読み取る
成功任意の 2xx
410 Goneただちにサブスクリプションを無効にする
リダイレクト追従しない。3xx は失敗した試行
タイムアウト試行あたり 10 秒
試行9 回: ただちに、その後 30 秒、2 分、10 分、30 分、1 時間、3 時間、6 時間、12 時間の待機を挟んで(最後は最初から約 22.7 時間後)
自動無効化10 回連続で配信のすべての試行が失敗した後。再び有効にするとカウントはリセットされる
シークレットwhsec_…。作成時とローテーション時に一度だけ表示
URLhttps:// のみ。公開 DNS 名(IP アドレス不可)、認証情報なし、ポートは 443 または 1024 以上。試行のたびに再確認し、プライベートアドレスやクラウドのメタデータアドレスは拒否
サブスクリプションワークスペースあたり 25
履歴イベント、配信、試行は 30 日間保持

フック ​

フックは distribution 自身のホスト上の URL(https://{slug}.edge.deca-dev.com/_hooks/{hook}) で、割り当てたカスタムドメインの同じパスでも機能します。distribution に live deployment がある 場合に動作します。パスワード保護は /_hooks には適用されません。送信元の署名が認証になります。

プリセット ​

プリセット検証内容冪等キー
standard-webhooks{webhook-id}.{webhook-timestamp}.{body} に対する webhook-signature、許容差 5 分。シークレットは whsec_ で始まるwebhook-id
stripe{t}.{body} に対する Stripe-Signature t=…,v1=…、許容差 5 分ボディの id(evt_…)
githubX-Hub-Signature-256: sha256=<hex>X-GitHub-Delivery
slackv0:{timestamp}:{body} に対する X-Slack-Signature: v0=<hex>、許容差 5 分。url_verification には challenge で応答ボディの event_id
lineX-Line-Signature、base64イベントが 1 件なら その webhookEventId。複数件のバッチでは、すべての events[].webhookEventId をカンマで連結した文字列の SHA-256 に line: を付けたもの
shopifyX-Shopify-Hmac-Sha256、base64X-Shopify-Webhook-Id
hmac指定したヘッダー内のボディの HMAC-SHA256: config.header(既定は x-signature)、config.encoding は hex または base64、任意で config.prefixIdempotency-Key ヘッダー
token秘密のパスセグメント: /_hooks/{hook}/{token}。トークンは Edge が生成し、一度だけ表示Idempotency-Key ヘッダー

冪等性 ​

Edge は次の順でキーを選びます。

  1. プリセットの送信元 id(上の表)。
  2. リクエストヘッダー Idempotency-Key。
  3. sha256(body)。フックに dedupe_body: true がある場合のみ。
  4. それ以外はキーなし。すべてのリクエストが新規として扱われる。

あるキーを持つ最初のリクエストが 受信記録(receipt) を作成し、hook.received を発行します。 同じフックに同じキーで届いた後続のリクエストには、200、最初の receipt_id、"replay": true、 ヘッダー Edge-Idempotent-Replay: true が返ります。イベントは発行されず、アクションも実行され ません。受信記録は 7 日間保持されます。キーで検索するには edge_hook_receipt_get または GET /v1/distributions/{id}/hooks/{hook_id}/receipts/{key} を使います。

レスポンス ​

ステータス意味
200受け付けた: {"ok": true, "receipt_id", "replay", "idempotency_key"}。Slack の検証には {"challenge"} を返す
400冪等キーが 255 文字を超えている
401署名、トークン、またはタイムスタンプの検証に失敗。詳細は返さない
404このホストにその名前の有効なフックが無い、または署名方式のフックにトークンが付いている
405POST ではない
413ボディが 256 KB を超えている

受信記録のステータス ​

ステータス意味
accepted保存済み。イベントの送出待ち
dispatchedアクションを実行中、または再試行待ち(result.retrying)
succeededイベントを送出し、アクション(あれば)も完了。詳細は result
failedアクションが失敗した。理由は result.error

アクション ​

config.action動作
{"kind": "invalidate", "paths": ["/blog/*"]}1〜15 個のビューアパスについて CDN キャッシュをクリアする
{"kind": "promote_latest"}live のものより後に作成された最新の ready deployment を promote する。無ければ何もしない
{"kind": "enqueue", "queue": "stripe-events"}リクエストごとに distribution のキューへメッセージを 1 件送る。queue.send が必要
{"kind": "workflow_start", "script_id": "01J…", "name"?: "onboard"}その関数のワークフロー実行を開始する。workflow.write が必要
{"kind": "workflow_signal", "run_id_from": "$.data.run_id", "signal": "paid"}ペイロードのそのパスにある id の実行にシグナルを送る。実行は同じ distribution にある必要がある。workflow.write が必要
{"kind": "wasm", "script_id": "01J…"}受け付けたリクエストごとに、その関数を 200 のあと 1 回実行する。関数は同じ distribution にある必要がある

enqueue、workflow_start、workflow_signal は {hook, receipt_id, idempotency_key, headers, payload} をメッセージ本文、実行の input、シグナルのペイロードとして渡し、受信記録の result に message_id、run_id、created、delivered を残します。受け付けたリクエストごとに 1 回だけ実行されます。キューが満杯、送信レートが上限超え、または distribution の実行中の実行が上限に達している場合は、5 分ごとに 24 時間再試行します(result.retrying)。それ以外の拒否(not_found、too_large、run_finished)は受信記録を失敗にします。Webhook をキューやワークフローに受け渡す を参照してください。

wasm はリクエストランナーで hook.received イベントを /_hooks/{slug} に POST します。2xx なら受信記録は succeeded です。受信記録の result には status_code、version、duration_ms、function_event_id が入ります。関数の出力は edge_function_logs に source hook で残ります。ワーカーが再起動すると 2 回実行されることがあるため、関数は data.idempotency_key で重複を除いてください。プロバイダの Webhook を受ける を参照してください。

invalidate と promote_latest は本番サイトを変更します。誤った deployment を promote した場合は パッチ、公開、切り戻し に従って切り戻してください。

制限値
distribution あたりのフック数20
ボディ256 KB
レート/_hooks 全体で、クライアント IP ごとに 5 分あたり 600 リクエスト

form.* を購読するには、さらに form.forward が必要です。{hook_id} にはフックの id または 名前を指定できます。

ルート、ツール、コマンドは、それぞれのページでスコープごとに並んでいます。

  • HTTP API — 各ルートと必要なスコープ
  • MCP — 各ツールと必要なスコープ
  • CLI — 各コマンドと必要なスコープ

あわせて読む ​