Jinba FlowでHTTP Webhookを受信する

外部サービスから公開フローへリクエストを送る場合はINPUT_WEBHOOKを使います。value入力に渡されたリクエストを表すJSON文字列を解析し、resultに返します。公開フローのURLについては公開を参照してください。

Webhookリクエストの値を渡す

JSONにはmethod、url、文字列値のheaders、bodyが必要です。文字列値のqueryとparamsは任意です。任意のdescription入力でステップに説明を付けられます。

- id: receive_webhook
  tool: INPUT_WEBHOOK
  input:
    - name: value
      value: '{"method":"POST","url":"https://example.com/orders","headers":{"content-type":"application/json"},"body":{"orderId":"123"}}'

公開フローでは、公開エンドポイントからリクエストを渡します。ローカル確認では上のvalueを使い、result.body.orderIdが123であることを確認します。後続ステップではsteps.receive_webhook.result.bodyを参照できます。

受信した注文を処理する

元のガイドにあった、Webhookの結果を後続のAIステップに渡す例です。入力結果のbodyを使います。

- id: summarize_order
  tool: OPENAI_INVOKE
  needs: [receive_webhook]
  input:
    - name: prompt
      value: "注文 {{steps.receive_webhook.result.body.orderId}} を出荷担当者向けに要約してください。"

実際の送信元につなぐ前に、要約に注文IDが含まれることを確認してください。

送信元の署名を検証する

WebhookのエンドポイントはPOST https://<your-flow-host>/api/v2/external/flows/<flow-id>/webhook-runです。フローの公開バージョンを実行するため、トリガーを変更したら公開してください。公開バージョンにINPUT_WEBHOOKステップがない場合は404を返します。デフォルトでは署名のないリクエストも受け付けます。HMAC-SHA256署名を必須にするには、ステップのconfigに次の項目を設定します。

設定	デフォルト	説明
`requireSignature`	`false`	`true`にすると、すべてのリクエストに署名を要求します
`signatureSecret`	—	HMACの鍵。リテラル値で指定します。`{{ secrets.X }}`形式のテンプレートはこのルートでは展開されず、拒否されます
`signatureHeader`	—	署名（16進ダイジェスト）を載せるヘッダー名。省略時は`x-webhook-signature`、`x-hub-signature`、`x-stripe-signature`、`x-shopify-hmac-sha256`、`x-discord-signature`、`x-slack-signature`のうち最初に存在するものを使います
`timestampHeader`	—	送信元のUnixタイムスタンプ（秒またはミリ秒）を載せるヘッダー名。設定すると署名の対象は生のボディではなく`<timestamp>.<raw body>`になり、`timestampTolerance`より古い配信は拒否され、以前と同じ署名の配信は新しい実行を開始せずに応答されます
`timestampTolerance`	`300`	タイムスタンプ付き配信の最大経過時間（秒）
`allowedContentTypes`	`application/json`、`application/x-www-form-urlencoded`、`text/plain`、`application/xml`、`text/xml`	エンドポイントが受け付けるContent-Type

- id: receive_webhook
  tool: INPUT_WEBHOOK
  config:
    - name: requireSignature
      value: true
    - name: signatureHeader
      value: x-webhook-signature
    - name: signatureSecret
      value: "replace-with-the-shared-secret"
  input:
    - name: description
      value: "注文システムからの署名付きWebhook"

requireSignatureが有効なのに使えるsignatureSecretがない場合や、セキュリティ設定が不正な場合は、未署名で実行せずすべてのリクエストを401で拒否します。署名がない、または一致しないリクエストも同様です。

Webhook入力エラーを調べる

InputWebhookToolエラーが出た場合は、valueが正しいJSONで、method、url、headers、bodyに必要な型の値があるか確認します。このツールの実行処理はリクエスト形式を解析しますが、ステップにrequireSignatureを設定していない限り、このステップだけで送信元の認証を確認したことにはなりません。

​Webhookリクエストの値を渡す

​受信した注文を処理する

​送信元の署名を検証する

​Webhook入力エラーを調べる

Webhookリクエストの値を渡す

受信した注文を処理する

送信元の署名を検証する

Webhook入力エラーを調べる