イベント、Webhook、フック
Webhook は Edge のイベントを HTTPS エンドポイントに送ります。フック は https://{slug}.edge.deca-dev.com/_hooks/{hook} で他サービスからの Webhook を受け取ります。 どちらもエージェントまたは HTTP API で設定します。web app ではまだ管理できません。エージェントは 同じ情報を MCP リソース edge://webhooks から読み取れます。
全体の関係は イベントと Webhook を、ホストについては 環境とドメイン を参照してください。
イベントタイプ
| タイプ | 分類 | 送信されるタイミング | data のフィールド |
|---|---|---|---|
deployment.created | lifecycle | deployment が作成された(rollback によるものを含む) | deployment_id, from_deployment_id |
deployment.ready | lifecycle | プレビューが公開された | deployment_id, preview_url |
deployment.failed | lifecycle | deployment を公開できなかった | deployment_id |
deployment.promoted | lifecycle | 本番サイトがこの deployment に切り替わった | deployment_id, previous_deployment_id, schedule_id(予約によって promote された場合) |
deployment.scheduled | lifecycle | promote、公開停止、復元が予約された | schedule_id, action, deployment_id, run_at |
deployment.schedule_cancelled | lifecycle | 未実行の予約が取り消された | schedule_id, action, deployment_id, run_at |
deployment.schedule_failed | lifecycle | 予約を実行できなかった。deployment が ready でない、1 日以上遅れた、またはエラー | schedule_id, action, deployment_id, run_at, error |
distribution.created | lifecycle | distribution が作成された | slug |
distribution.updated | lifecycle | distribution の設定が変更された | changes — 差分のあるトップレベルの設定名 |
distribution.taken_down | lifecycle | 公開中のホストが 410 Gone または一時的なリダイレクトを返すようになった | mode, location, schedule_id |
distribution.restored | lifecycle | 公開停止が解除された | schedule_id |
distribution.destroyed | lifecycle | distribution が削除された | slug |
domain.verified | lifecycle | ドメインの所有権が検証された | fqdn, status |
domain.active | lifecycle | ドメインが証明書付きでトラフィックを配信している | fqdn, status |
domain.failed | lifecycle | 検証またはプロビジョニングが失敗した | fqdn, status |
domain.attached | lifecycle | ドメインが distribution に割り当てられた | fqdn |
domain.detached | lifecycle | ドメインの割り当てが解除された | fqdn |
function.build.succeeded | lifecycle | 関数ランタイムのビルドが新しいバージョンを公開した | script_id, version |
function.build.failed | lifecycle | 関数ランタイムのビルドが失敗した | script_id |
cron.fired | lifecycle | emit ターゲットの cron が実行された(実行ごとに 1 件) | job_id, attempt, owner_kind, owner_id, scheduled_for |
cron.run.failed | lifecycle | cron の実行が失敗し、再試行も残っていない | cron_id, name, job_id, attempt, error_code |
cron.run.missed | lifecycle | cron の実行時刻に 1 日以上遅れて到達したため実行しなかった | cron_id, name, job_id, scheduled_for |
workflow.completed | lifecycle | ワークフローの実行のステップが done を返した | run_id, name, script_id, step |
workflow.failed | lifecycle | ワークフローの実行が失敗した。ステップが fail を返した、再試行を使い切った、タイムアウト用のステップなしで待ちがタイムアウトした、または実行の寿命が過ぎた | run_id, name, script_id, step, error, error_code |
queue.backlog.high | lifecycle | キューに 10,000 件を超えるメッセージがある、またはいちばん古いメッセージが 1 時間以上待っている(キューごとに 1 時間に 1 回まで) | queue_id, name, depth, oldest_ready_age_seconds, depth_threshold, age_threshold_seconds |
queue.message.dead_lettered | data | キューのメッセージが最後の試行を使い切り dead になった | queue_id, name, message_id, attempts, error, job_id, body |
form.submitted | data | /_submit がフォームの送信を保存した | form_id, submission_id, path, envelope(フォームがアップロードを受け付ける場合は files 付き) |
form.file.scanned | data | 送信に添付されたファイルのスキャンが clean、rejected、scan_failed のいずれかで終わった。ファイルごとに 1 回 | form_id, submission_id, file |
hook.received | data | フックが検証済みのリクエストを受け付けた | hook_id, hook_slug, preset, receipt_id, idempotency_key, key_source, headers, payload |
goal.converted | volume | サブスクリプションが選んだコンバージョンゴールに人間の訪問が一致した | 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.created | security | Webhook サブスクリプションが作成された | webhook_id, url_host, event_types |
webhook.subscription.disabled | security | 失敗が続いたためサブスクリプションが無効になった | webhook_id, url_host, reason |
webhook.ping | test | Webhook のテストで、そのサブスクリプションにだけ送られる | webhook_id |
access.rule.created | security | アクセスルールが追加された | rule_id, kind, applies_to |
access.rule.deleted | security | アクセスルールが削除された | rule_id, kind, sign_out |
access.sessions.revoked | security | 1 人、または全員がサインアウトされた | sub, all |
access.network_rule.created | security | IP または国のルールが追加された | rule_id, kind, value, applies_to |
access.network_rule.deleted | security | IP または国のルールが削除された | rule_id, kind, value, applies_to |
access.network_mode.updated | security | ネットワークルールとサインインの組み合わせ方が変わった | 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 に含めます。
{
"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_id | form.* のみ: ひとつのフォーム |
filters.hook_slug | hook.* のみ: ひとつのフック |
filters.goal_id | goal.* のみ: ひとつのゴール |
Webhook の配信
Edge は Standard Webhooks に従っているため、そのライブラリの どれでも Edge からの配信を検証できます。
ボディ
{
"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-signature | v1,<base64> — {webhook-id}.{webhook-timestamp}.{body} をシークレットで HMAC-SHA256 したもの。シークレットのローテーション後 24 時間は、スペース区切りで 2 つの値 |
edge-event-type | イベントタイプ |
edge-delivery-attempt | 最初の試行は 1、2 回目は 2、… |
content-type | application/json |
user-agent | DECA-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_…。作成時とローテーション時に一度だけ表示 |
| URL | https:// のみ。公開 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_…) |
github | X-Hub-Signature-256: sha256=<hex> | X-GitHub-Delivery |
slack | v0:{timestamp}:{body} に対する X-Slack-Signature: v0=<hex>、許容差 5 分。url_verification には challenge で応答 | ボディの event_id |
line | X-Line-Signature、base64 | イベントが 1 件なら その webhookEventId。複数件のバッチでは、すべての events[].webhookEventId をカンマで連結した文字列の SHA-256 に line: を付けたもの |
shopify | X-Shopify-Hmac-Sha256、base64 | X-Shopify-Webhook-Id |
hmac | 指定したヘッダー内のボディの HMAC-SHA256: config.header(既定は x-signature)、config.encoding は hex または base64、任意で config.prefix | Idempotency-Key ヘッダー |
token | 秘密のパスセグメント: /_hooks/{hook}/{token}。トークンは Edge が生成し、一度だけ表示 | Idempotency-Key ヘッダー |
冪等性
Edge は次の順でキーを選びます。
- プリセットの送信元 id(上の表)。
- リクエストヘッダー
Idempotency-Key。 sha256(body)。フックにdedupe_body: trueがある場合のみ。- それ以外はキーなし。すべてのリクエストが新規として扱われる。
あるキーを持つ最初のリクエストが 受信記録(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 | このホストにその名前の有効なフックが無い、または署名方式のフックにトークンが付いている |
405 | POST ではない |
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 または 名前を指定できます。
ルート、ツール、コマンドは、それぞれのページでスコープごとに並んでいます。