Skip to content

Webhook をキューやワークフローに受け渡す ​

フック は送信元の署名を確認し、すぐに 200 を返します。アクションを設定すると、受け付けた各リクエストをジョブエンジンにも渡せます。

アクション動作
enqueuedistribution の キュー にメッセージを 1 件送る
workflow_start関数の ワークフロー実行 を開始する
workflow_signalペイロードにある id の実行にシグナルを送る(決済サービスが支払いを確定したときなど)

送信元があなたのコードを待つことはありません。アクションは 200 の直後に、受け付けたリクエストごとに 1 回だけ実行されます。送信元が再送しても、メッセージや実行は 2 つになりません。

hook.write に加えて、enqueue には queue.send、ワークフローのアクションには workflow.write が必要です。キューや関数は distribution に先に作っておきます。Web アプリではまだフックを管理できません。エージェント、CLI、API を使います。

1. 各リクエストをキューに送る ​

この例では Stripe のイベントをキュー stripe-events に溜め、関数が自分のペースでまとめて処理できるようにします。

text
acme-marketing に stripe という Stripe の Webhook 受信先を追加して、すべてのイベントを
stripe-events キューに入れてください。署名シークレットは whsec_8Qp… です。
bash
echo '{"action": {"kind": "enqueue", "queue": "stripe-events"}}' |
  edge hooks create acme-marketing --slug stripe --preset stripe --secret 'whsec_8Qp…' --config -
bash
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 を実行します。各メッセージの本文は検証済みのリクエストです。

json
{
  "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 を使います。たとえば登録フォームでオンボーディングの実行を開始します。

json
{"action": {"kind": "workflow_start", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7", "name": "onboard"}}

実行の input はキューのメッセージと同じオブジェクトです。設定には 1 節のコマンドを使い、既存のフックには edge hooks update を使います。

3. 待機中の実行を再開する ​

シグナルを wait しているワークフローのステップは、プロバイダー自身が再開できます。Stripe の metadata など、プロバイダーが送り返す場所に実行 id を入れ、フックにその場所を教えます。

text
acme-marketing の stripe フックで、$.data.object.metadata.run_id にある id のワークフロー実行に
paid シグナルを送るようにしてください。
bash
echo '{"action": {"kind": "workflow_signal", "run_id_from": "$.data.object.metadata.run_id", "signal": "paid"}}' |
  edge hooks update acme-marketing stripe --config -
bash
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. 結果を確認する ​

受信記録にはアクションが何をしたかが残ります。

text
acme-marketing の stripe フックの最近の受信記録を見せてください。
bash
edge hooks receipts acme-marketing stripe
bash
curl -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受信記録は失敗し、アクションは再実行されない

次に ​