Webhookの配信を確認して再配信する

配信ログにはdosyaが試行した内容、次の再試行の予定時刻、受信側が返した内容が表示されます。イベント生成の問題と、ネットワーク、署名、アプリケーションの問題を区別するために使用してください。手動でイベントを再配信する前に受信側を修正します。

手順

連携 → Webhookを開き、目的のワークスペースを有効にしてエンドポイントを探し、配信を選択してください。最近の配信には各ページに10行が表示され、列は次のとおりです。

• イベントはfile.uploadedなど購読したevent_typeです。
• 作成日時は配信レコードが追加された時刻です。
• 状態は保留中、成功、失敗のいずれかです。
• 応答にはHTTPステータス、通信エラーが記録された場合はError、結果がまだ保存されていない場合は-が表示されます。
• 試行回数は最初のリクエストを含む完了したリクエストの数です。
• 次の再試行は失敗した配信が保留中の間だけ表示されます。

応答セルにカーソルを合わせると記録されたエラーやレスポンスの一部を読めます。dosyaはレスポンスの先頭最大500文字を保持するため、okなど短い内容の応答を返してください。トークン、個人情報、スタックトレース、リクエストのペイロードを応答に含めないでください。

送信される各リクエストにはX-Dosya-Event-IdとX-Dosya-Delivery-Idの両方が含まれます。保持された配信の自動試行は同じ識別子を使用します。手動の再配信は元のイベントIDとJSONペイロードを保持して新しい配信IDを作成します。どちらの場合も安全に処理できるよう、イベントIDで業務処理の重複を排除してください。

自動再試行について

HTTPステータス200〜299はすべて成功です。2xx以外のレスポンス、ネットワークエラー、拒否されたエンドポイントURL、または受信側が10秒以内に完了しない場合は失敗した試行としてカウントされます。dosyaは許可されたHTTPSリダイレクトを1回たどれます。さらにリダイレクトされると2xx以外の失敗になります。

試行は合計6回です。即時の初回試行が失敗した後、30秒、2分、10分、1時間、6時間後に後続の試行が予定されます。キューとネットワークの時間により実際の遅延は長くなる場合があります。6回目の試行が失敗すると配信は失敗になり、次の再試行はありません。

エンドポイントはイベントをまたいで15回連続で配信試行が失敗すると無効になります。1回成功すると連続失敗のカウントはリセットされます。カードに配信が繰り返しできなかったため、自動で無効化されました。と表示されたら、先に受信側を修正してから再度有効化を選択してください。カウンターはクリアされますが、送られなかった製品イベントがさかのぼって配信されることはありません。

失敗した試行を調べる

1. イベントID、配信ID、イベントの種類、HTTPレスポンス、記録時刻をインシデントの記録にコピーします。署名と署名シークレットは含めないでください。
2. 配信IDを受信側のアクセスログと照合します。通常、リクエストが届いていない場合はDNS、TLS、公開アドレスの検証、ファイアウォール、タイムアウトの問題が考えられます。
3. 4xxレスポンスでは署名の解析と受信側のルートまたは認証ミドルウェアを確認してください。5xxレスポンスでは再試行前にアプリケーションの問題を修正します。
4. ハンドラーが変更されていない本文を読み、JSONを解析する前にX-Dosya-Signatureを検証することを確認します。
5. 記録したペイロードの再実行は制御されたテスト環境でのみ行い、意図的に無効な署名を使った否定テストを実施します。行を緑色にするために本番環境で検証を回避しないでください。
6. 受信側が2xxを返す前に重複排除レコードとキューに入れたジョブを永続化するようにしてください。

配信を開けない場合、Webhookの管理にはそのワークスペースのメンバーシップとmanage_settings権限が必要です。REST APIにはさらにフルアクセス認証情報が必要で、なければAPI key scope 'full' requiredが返されます。

修正後に再配信する

対象行の再配信を選択してください。トーストの再配信を待機中にしました。は新しい配信レコードが作成されたことを意味し、受信側が受け入れた証拠ではありません。1ページ目に戻って最近の配信を更新し、新しい行を探してください。成功した場合は2xxレスポンスと1回の試行が表示されます。

RESTでの手順は次のとおりです。

curl --fail-with-body --silent --show-error \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID/deliveries?page=1&per_page=25" \
  -H "Authorization: Bearer $DOSYA_API_KEY"

curl --fail-with-body --silent --show-error --request POST \
  "https://api.dosya.dev/api/webhooks/$DOSYA_WEBHOOK_ID/deliveries/$DOSYA_DELIVERY_ID/redeliver" \
  -H "Authorization: Bearer $DOSYA_API_KEY"

一覧エンドポイントはpageを受け付け、per_pageを10〜100に制限します。標準は25です。エンドポイントが存在しない場合はWebhook not found、そのエンドポイントに属さない配信にはDelivery not foundが返されます。手動再配信はユーザーごとに300秒あたり20回までで、超えるとRetry-After付きの429が返される場合があります。

期待される結果

新しい配信が成功に達し、受信側のログがその配信IDとイベントIDに一致し、後続の状態が1回だけ変わります。元の失敗行はインシデントの証拠として保持してください。Webhookを削除するとエンドポイントと配信履歴全体が完全に削除されます。

関連ガイド

• 購読するイベントの種類を選ぶ
• 処理前に署名を検証する
• Webhook配信の問題を解決する