Webhookの配信に速やかに応答する

dosyaはHTTPの2xxレスポンスをすべて成功とみなします。受信側にはリクエストの検証と応答に10秒あるため、リクエストの処理中に永続的な受け入れを行い、時間のかかる業務処理はその後に実行してください。

手順

1. JSONを解析する前に、変更されていないリクエストのバイトデータとX-Dosya-Signatureヘッダーを読み取ります。t=<unix-seconds>,v1=<hex>の値を分割し、エンドポイントの署名シークレットを使って${t}.${rawBody}のHMAC-SHA256を計算してください。
2. tを安全な整数として解析し、受信側の時刻との差が300秒を超える場合は拒否してください。次に計算したダイジェストとv1を定数時間の操作で比較します。古い、不正な、または一致しない署名のペイロードはキューに追加しないでください。
3. X-Dosya-Event-Id、X-Dosya-Delivery-Id、X-Dosya-Event-Typeを取得し、検証済みの生のイベントとイベントIDの冪等性レコードを永続ストレージに確定します。
4. トランザクションが確定したら、空または安全な内容の2xxレスポンスを速やかに返してください。後続のAPI呼び出し、メディア処理、通知など時間のかかる処理は応答後にワーカーで実行します。
5. リクエスト全体を10秒未満に収めてください。タイムアウト、ネットワークエラー、dosyaが許可する1回のリダイレクト後も残る3xx、2xx以外のステータスは失敗した試行として記録されます。
6. 連携 → Webhookで配信を開き、成功、レスポンスのステータス、試行が1回であることを確認してください。dosyaはレスポンスを最大500文字保存するため、応答本文にシークレットや非公開のペイロードを返さないでください。

最初の失敗後の再試行は30秒後に予定され、その後は2分、10分、1時間、6時間の間隔です。再試行の確認処理は10分ごとに実行されるため、最も早い予定時刻より後になる場合があります。

期待される結果

有効な配信が1回だけ永続的に受け入れられ、10秒の期限前に2xxが返されます。最近の配信には成功が表示され、時間のかかる処理は再試行を発生させずに別途続行されます。

有効なリクエストがタイムアウトします。 永続キューへの確定後に処理を移し、プロキシやプラットフォームのタイムアウトを確認してください。受信側の処理時間を増やしてもdosyaの10秒の上限は変わりません。

署名が一致しません。 再シリアライズしたJSONではなく、空白を含めて受信した正確なバイトデータをハッシュし、現在のエンドポイントシークレットで検証してください。

関連ガイド

• Webhook署名を検証する
• 配信を確認する