失敗したdosya Webhook配信の問題を解決する

同じ配信について、エンドポイントの配信テーブルと受信側のログを使用してください。テーブルにはイベント、作成時刻、ステータス、レスポンス、試行回数、次の再試行が表示されます。受信側はシークレットでないイベントIDと配信IDをログに記録する必要があります。本番エンドポイントで検証を無効にして署名の問題を調べないでください。

手順

1. エンドポイントが属するワークスペースで連携 → Webhookを開いてください。
2. カードが有効であり、file.uploaded、file.deleted、share.accessedのうち目的のイベントが含まれていることを確認します。
3. 配信を展開して失敗した行を開き、イベントの種類、配信とイベントの識別子、レスポンスステータス、試行回数、次の再試行、エラー、機密情報を除いたレスポンスの一部を記録します。
4. 行の試行時刻を受信側とエッジまたはプロキシのログと比較してください。リクエストが届いていない場合はURL、DNS、SSRFの検証、接続、上流のプロキシを確認します。届いたリクエストが拒否された場合は受信側の検証または処理を確認してください。

Webhookの管理にはワークスペースのメンバーシップとmanage_settingsが必要です。標準のオーナーと管理者が該当します。Webhookの操作が表示されない場合や403 You don’t have permission to manage webhooksはワークスペースのロールで修正する必要があります。キーをローテーションしてもそのメンバーの権限は広がりません。

問題が起きた受信側の境界を特定する

症状	対処
URLの作成や編集で**Endpoint URL not allowed: …**が返る	公開HTTPS受信側を使用してください。localhost、プライベートネットワーク、許可されないDNSやアドレスは登録時と配信時に拒否されます。
受信側にPOSTが届かない	保存済みURL、公開DNSとTLS、プロキシルート、ファイアウォール、エンドポイントが有効かを確認してください。配信にURL検証エラーが記録されていないかも確認します。
受信側が3xxを返す	最終的な安定したHTTPS URLを設定してください。dosyaは許可されたリダイレクトを最大1回たどり、2回目は失敗として記録します。
配信がタイムアウトする	認証と永続キューへの追加後に応答してください。受信側には10秒あり、長い処理は非同期で行います。
4xx/5xxが返る	受信側のログでX-Dosya-Delivery-Idを確認し、そのルートを修正して、受け入れ後にのみ2xxを返してください。2xx以外はすべて失敗した試行です。
署名が一致しない	エンドポイントの現在のwhsec_…シークレットで変更されていないリクエストのバイトデータを検証してください。HMACを計算する前にJSONを解析・再整形しないでください。
エンドポイントに**配信が繰り返しできなかったため、自動で無効化されました。**と表示される	受信側を修正してテストし、再度有効化を選択してください。再有効化は連続失敗カウンターをクリアしますが、過去の失敗した処理を修復しません。
イベントが2回処理された	エンベロープのイベントidで重複を排除してください。再試行はそのイベントの識別情報を保持し、手動再配信は同じイベントとペイロードの新しい配信行を作成します。

dosyaはtimestamp + "." + raw_bodyにHMAC-SHA256で署名します。ヘッダーはX-Dosya-Signature: t=TIMESTAMP,v1=LOWERCASE_HEX_HMACです。ダイジェストを定数時間で比較し、受信側の時計から300秒を超えて離れたタイムスタンプを拒否してください。X-Dosya-Event-Id、X-Dosya-Event-Type、X-Dosya-Delivery-Idも記録します。これらのヘッダーはどれも署名検証の代わりにはなりません。

シークレットをローテーションを使用した場合、古いシークレットは即座に使えなくなっています。新しく表示された値で受信側を更新してください。併用期間はありません。表示された値を失った場合は再度ローテーションする必要があります。署名とシークレットをリクエストログに含めないでください。

再試行のタイミング

配信の試行は合計6回です。最初は即時に実行され、失敗後は30秒、2分、10分、1時間、6時間後に続きます。スケジュールやネットワーク処理によって遅れることがあります。6回目の試行が失敗すると配信は失敗のままになります。

イベントをまたぐ十五回連続の失敗でエンドポイントが自動的に無効になります。試行が成功すると連続失敗はリセットされます。制御されたテストが成功できるようになってから再度有効にしてください。そうしなければ再び失敗し始めます。

dosyaに保持される受信側のレスポンス本文は500文字までです。短く簡潔な応答を返してください。認証情報、スタックトレース、非公開の内容をレスポンスに含めないでください。

制御されたテストを送信する

テストイベントを送信を選択してください。これにより、データにtest: true、ファイルID test_file、名前test.txt、容量12を含む合成のfile.uploadedイベントが作成されます。エンドポイントが別のイベントだけを購読していても送信されるため、受信側は本番コンテンツとして扱わずテストフラグを識別する必要があります。

トーストのテストイベントを送信しました。はテストが待機中になったことだけを示します。配信を更新して成功を待ち、受信側が認証済みイベントを正確に1件保存したことを確認してください。テストと手動再配信の各ルートはユーザーごとに300秒あたり20回までです。429レスポンスのRetry-Afterに従ってください。

合成テストの後、エンドポイントが実際に購読する無害なイベントを1件発生させます。イベントのワークスペースとペイロードのメタデータを確認し、後続の処理が1回だけ実行されたことを確認してください。

安全に再配信する

元のリクエストがすでに後続の状態を変更したか確認してから、再配信を使用してください。タイムアウトや応答の喪失により、dosyaでは失敗と記録されても受信側は成功している場合があります。まずイベントIDで検索し、ハンドラーを冪等にしてから再配信を1件待機中にします。UIの**再配信を待機中にしました。 — 新たな配信の試行を予約しました。**は最終的な配信結果ではありません。新しい行を確認してください。

エンドポイントを削除すると配信履歴が完全に削除され、すでに受信されたペイロードは回収できません。削除前にシークレットを含まない証拠を保存してください。シークレットのローテーションも即時に行われ、古い値は元に戻せません。

期待される結果

新しいテスト配信が目的のHTTPSエンドポイントに届き、生の本文の署名検証を1回通過してタイムアウト前に成功レスポンスを返し、重複した副作用を作成しません。

関連付けた情報を添えて対応を依頼する

エンドポイントID、イベントIDと配信ID、イベントの種類、UTCまたはローカルの試行時刻、レスポンスステータス、試行回数、機密情報を除いた表示内容やエラー、受信側のフレームワーク、リクエストがエッジとアプリケーションに届いたかを伝えてください。署名シークレット、署名全体、認証ヘッダー、非公開のペイロード項目、認証情報は含めないでください。

関連ガイド

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