Webhook をキューやワークフローに受け渡す
フック は送信元の署名を確認し、すぐに 200 を返します。アクションを設定すると、受け付けた各リクエストをジョブエンジンにも渡せます。
| アクション | 動作 |
|---|---|
enqueue | distribution の キュー にメッセージを 1 件送る |
workflow_start | 関数の ワークフロー実行 を開始する |
workflow_signal | ペイロードにある id の実行にシグナルを送る(決済サービスが支払いを確定したときなど) |
送信元があなたのコードを待つことはありません。アクションは 200 の直後に、受け付けたリクエストごとに 1 回だけ実行されます。送信元が再送しても、メッセージや実行は 2 つになりません。
hook.write に加えて、enqueue には queue.send、ワークフローのアクションには workflow.write が必要です。キューや関数は distribution に先に作っておきます。Web アプリではまだフックを管理できません。エージェント、CLI、API を使います。
1. 各リクエストをキューに送る
この例では Stripe のイベントをキュー stripe-events に溜め、関数が自分のペースでまとめて処理できるようにします。
acme-marketing に stripe という Stripe の Webhook 受信先を追加して、すべてのイベントを
stripe-events キューに入れてください。署名シークレットは whsec_8Qp… です。echo '{"action": {"kind": "enqueue", "queue": "stripe-events"}}' |
edge hooks create acme-marketing --slug stripe --preset stripe --secret 'whsec_8Qp…' --config -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…",
"config": { "action": { "kind": "enqueue", "queue": "stripe-events" } } }'エージェントは edge_hook_create を実行します。各メッセージの本文は検証済みのリクエストです。
{
"hook": "stripe",
"receipt_id": "rcpt_01M4Y…",
"idempotency_key": "evt_3Q…",
"headers": { "stripe-signature": "…" },
"payload": { "id": "evt_3Q…", "type": "payment_intent.succeeded", "data": { … } }
}payload はリクエストを解析した JSON(またはフォームの項目、またはテキスト)です。headers には x-github-event など Edge が転送するプロバイダーのヘッダーが入ります。128 KiB を超える本文はキューに入れられず、受信記録は too_large で失敗します。
Edge がアクションを再試行しても、1 件の受信記録がキューに入れるメッセージは 1 件です。ただし、ほかのキューと同じくコンシューマーへの配信は少なくとも 1 回なので、receipt_id で重複を取り除いてください。
2. ワークフロー実行を開始する
リクエストごとに長い処理を始めるときは workflow_start を使います。たとえば登録フォームでオンボーディングの実行を開始します。
{"action": {"kind": "workflow_start", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7", "name": "onboard"}}実行の input はキューのメッセージと同じオブジェクトです。設定には 1 節のコマンドを使い、既存のフックには edge hooks update を使います。
3. 待機中の実行を再開する
シグナルを wait しているワークフローのステップは、プロバイダー自身が再開できます。Stripe の metadata など、プロバイダーが送り返す場所に実行 id を入れ、フックにその場所を教えます。
acme-marketing の stripe フックで、$.data.object.metadata.run_id にある id のワークフロー実行に
paid シグナルを送るようにしてください。echo '{"action": {"kind": "workflow_signal", "run_id_from": "$.data.object.metadata.run_id", "signal": "paid"}}' |
edge hooks update acme-marketing stripe --config -curl -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": "workflow_signal",
"run_id_from": "$.data.object.metadata.run_id", "signal": "paid" } } }'run_id_from はペイロード内のパスで、$ に続けて .key と [index] を並べます。シグナルのペイロードはキューのメッセージと同じオブジェクトなので、次のステップは signal.payload.payload でイベントを読みます。実行は同じ distribution にある必要があり、そうでなければ受信記録は not_found で失敗します。すでに終わった実行の場合は run_finished で失敗します。
4. 結果を確認する
受信記録にはアクションが何をしたかが残ります。
acme-marketing の stripe フックの最近の受信記録を見せてください。edge hooks receipts acme-marketing stripecurl -s https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/stripe/receipts \
-H "Authorization: Bearer $EDGE_TOKEN"result | 意味 |
|---|---|
{"message_id": "msg_…", "duplicate": false} | キューに入った |
{"run_id": "wfr_…", "created": true} | 実行を開始した |
{"run_id": "wfr_…", "delivered": true} | シグナルを届けた。false のときは実行が待つまで Edge が保持する |
{"error": "queue_full", "retrying": true} | キューが満杯、送信レートが上限超え、または distribution の実行中の実行が多すぎる。Edge は 5 分ごとに 24 時間再試行する |
{"error": "not_found", …}、too_large、run_finished | 受信記録は失敗し、アクションは再実行されない |