> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook イベント辞書と一括再送

> Merchant Portal が追跡する 7 つの Webhook イベントタイプ、自社注文と照合するために各イベントが持つ識別子、ログの保持期間、そして Retry by Date で失敗した配信を期間指定でまとめて再送する方法。

Webhook は 3 つのページで扱っており、それぞれ異なる質問に答えます。

| 質問 | ページ |
| - | - |
| 配信契約は何か、エンドポイントは何を返すべきか、自動再試行はどう動くか？ | [Webhook 概要](/docs/ja/developer-docs/webhook/overview) と [Webhook の再試行](/docs/ja/developer-docs/webhook/retry) |
| 各イベントのペイロードには何が入っているか？ | [Webhook イベントタイプ一覧](/docs/ja/developer-docs/webhook/event-types) |
| Portal で 1 件の配信を確認するには、レコードがないのはなぜか、Resend がグレーアウトしているのはなぜか？ | [Webhook イベントログと手動再送](/docs/ja/support/portal-webhook-log-faq) |

**このページは辞書と一括ツールです**。Portal で追跡可能なイベントとして何が存在するか、自社レコードと照合するために
各イベントがどの識別子を持つか、ログはどこまで遡れるか、そして失敗を期間指定で一度にまとめて再送する方法を説明します。

## Portal はどのイベントタイプを追跡しますか？

7 つです。これは **Event Type** フィルターが提供する正確な集合であり、そのフィルターを空にしたときに検索される集合でもあります。

| `eventType` | Portal でのラベル | 発火条件 |
| - | - | - |
| `PAYMENT_NOTIFICATION` | Payment Notify | 決済が完了または失敗したとき |
| `REFUND_NOTIFICATION` | Refund Notify | 返金が完了または失敗したとき |
| `TOKENIZATION_NOTIFICATION` | Tokenization Notify | トークンが生成された、そのステータスが変わった、またはカードデータが更新されたとき |
| `SUBSCRIPTION_STATUS_NOTIFICATION` | Subscription Status Notify | サブスクリプション自体のステータスが変わったとき — 有効化、キャンセル、終了 |
| `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` | Subscription Period Notify | 課金期間が終了状態に到達したとき |
| `SUBSCRIPTION_CHANGE_NOTIFICATION` | Subscription Change Notify | サブスクリプションのアップグレードまたはダウングレードが完了したとき |
| `CHARGEBACK_NOTIFICATION` | Chargeback Notify | チャージバック案件が作成された、またはそのステータスが変わったとき |

無駄な検索を避けるための 2 つの点：

* **チャージバックのイベントはちょうど 1 つです。** チャージバックの作成と案件のステータス変更はすべて `CHARGEBACK_NOTIFICATION`
  として届きます。購読できる別のアラートイベントや、別のチャージバック返金イベントは存在しません。
* **`eventType` 列の値は上記の値そのものです。** Portal で読める値が、自社コードで照合する値です。分かりやすいラベルは表示専用です。

## Webhook を自社の注文と照合するにはどうすればよいですか？

すべてのレコードは 1 つの **Order ID** を持ち、それがどの識別子であるかはイベントによって異なります。対応表は次のとおりです。

| イベント | ログ内の Order ID | 自社側の照合キー |
| - | - | - |
| `PAYMENT_NOTIFICATION` | `acquiringOrderId` — Waffo の決済注文 | ペイロードに含まれるお客様の `merchantOrderId` |
| `REFUND_NOTIFICATION` | `acquiringRefundOrderId` — Waffo の返金注文 | 返金の加盟店注文 ID と、返金対象の元注文 |
| `TOKENIZATION_NOTIFICATION` | `tokenId` | 顧客に紐づけて保存したトークン |
| `SUBSCRIPTION_STATUS_NOTIFICATION` | Waffo のサブスクリプション ID | ペイロードに含まれるお客様の `merchantSubscriptionId` |
| `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` | Waffo のサブスクリプション ID | 同上、およびペイロード内の期間番号 |
| `SUBSCRIPTION_CHANGE_NOTIFICATION` | 変更によって生成された**新しい**サブスクリプション ID | 送信した変更リクエストと、ペイロード内の元のサブスクリプション ID |
| `CHARGEBACK_NOTIFICATION` | チャージバック通知自体の識別子 | **ペイロード内の `originalOrderId`** — 異議申し立ての対象となった決済注文 |

チャージバックの行は驚かれることが多いので、はっきり述べておきます。**元の決済注文番号でログを検索しても、チャージバック通知は
見つかりません。** そこでの Order ID 列は案件自体の識別子であり、お客様の注文ではありません。レコードを開き、リクエストボディから
`originalOrderId` を読み取ってください。逆方向にも同じ注意が当てはまります — チャージバックログの Order ID を自社システムの
キーとして使用しないでください。

サブスクリプションについては、アップグレードまたはダウングレードにより**新しい**サブスクリプション ID が生成されるため、
`SUBSCRIPTION_CHANGE_NOTIFICATION` は変更前に持っていたサブスクリプション ID とは一致しません。それをキーにしている場合は、
ペイロードから元の ID を読み取ってください。

## このうちどれを購読でき、URL はどこから来るのですか？

Portal で設定できるコールバック URL は 2 つのみで、残りはオブジェクトを作成した API 呼び出しに付随します。Webhook ログページで
URL を変更できるものはありません — このページは設計上、読み取り専用です。

| イベント | URL の出所 |
| - | - |
| `PAYMENT_NOTIFICATION` | 注文作成リクエストの `notifyUrl` |
| `REFUND_NOTIFICATION` | 返金リクエストの `refundNotifyUrl`。なければ Portal で設定された Refund Notify URL |
| `TOKENIZATION_NOTIFICATION` | トークン生成リクエストの `notifyUrl`。Tokenization Notify URL も Portal で設定可能 |
| サブスクリプションのイベント | サブスクリプション自体が保持する `notifyUrl` |
| `CHARGEBACK_NOTIFICATION` | Portal で設定された Chargeback Notify URL のみ — リクエストごとに渡すことはできない |

Portal 側の URL の設定は
[Portal セルフサービスセキュリティ設定](/docs/ja/support/portal-security-config-faq) で説明しています。イベントがログレコードを
まったく生成しなかった場合、通常の原因は URL が解決されなかったことです。
[Webhook イベントログと手動再送](/docs/ja/support/portal-webhook-log-faq) を参照してください。

## Webhook ログはどこまで遡れますか？

**90 日です。** ページのバナーにそう記載され、日付ピッカーでは 90 日より前の日を選択できず、Retry by Date も同じ期間に
制限されます。それより古いものについては、通知を探すのではなく、照会 API でオブジェクト自体を照会してください。

関連する 2 つの境界：

* ログは機能がリリースされた時点から始まります。それ以前の通知はバックフィルされないため、非常に古い取引で結果が空になるのは
  想定どおりであり、診断上の意味はありません。
* 一覧はデフォルトで **Submission Time** の新しい順に並びます。

## 失敗を期間指定で一度にまとめて再送できますか？

はい — **Retry by Date** がそのための機能です。エンドポイントが一定期間ダウンしていて、その期間の失敗を 1 件ずつクリックせずに
まとめて再配信したい、というまさにそのケースのために存在します。

| 入力 | 動作 |
| - | - |
| 時間範囲 | 必須。過去 90 日に限定され、その範囲外の日は選択できません。 |
| イベントタイプ | 任意、複数選択。空のままにすると 7 つすべてが対象になります。 |
| 見積もり | 入力を変更するたびに、ダイアログが一致する**失敗**レコードを集計し、確定前にその件数を表示します。 |

対象となるのは失敗レコードのみです — 成功したレコードや処理中のレコードは決して含まれないため、エンドポイントがすでに
受け入れたものを誤って再配信することはありません。

## 1 回のバッチで何件まで再送できますか？

**1 リクエストあたり最大 50 件です。** これは Retry by Date と複数選択の再送の両方に適用され、UI 上のヒントではなく
両側で強制されます。

実務上の意味：

| 状況 | 起きること |
| - | - |
| 見積もりが 0 | 確認ボタンは無効のまま — 送るものがない |
| 見積もりが 1〜50 | 確認して進める |
| 見積もりが 50 超 | ダイアログが警告し、確認ボタンは無効のまま：**時間範囲またはイベントタイプを絞り込んで**から確認する |

バッチは最初の 50 件に黙って切り詰められることは**ありません** — 上限を超えた範囲は即座に拒否されます。これは意図的な設計です。
切り詰められたバッチでは、大部分が再送されていないのに期間全体が再送されたと思い込んでしまいます。大量のバックログは、
スライスに分けて処理してください — まずイベントタイプで分けるとよいでしょう。通常、それが実際のインシデントの境目に沿って
期間を分割してくれます。

## 一括再送の後、何が返ってきますか？

レコードごとの結果が、単一の成功/失敗ではなく件数として集約されます。

| 結果 | 表示 |
| - | - |
| すべて成功 | *n record(s) resent successfully* |
| すべて失敗 | *Resend failed for all n record(s). Please try again later.* |
| 混在 | *n resent successfully, m failed.* |

「成功」とは、今回の試行でエンドポイントが配信を受け入れたことを意味します — バッチはリクエストがキューに入ったことではなく、
実際の配信結果を報告します。したがって、すべて失敗で返ってきたバッチは、エンドポイントがまだペイロードを受け入れていないことを
示しています。再送する前に修正してください。

見積もりと送信の間に状態が変わったレコード — たとえばその間に自動再試行で成功したもの — は、もう対象ではないため、
再送されずに失敗数として集計されます。

## 手動または一括の再送は、自動再試行の回数を消費しますか？

はい — 実際には修正していないエンドポイントに対して期間再送を行う前に、知っておくべきことです。

再送は自動試行と**同じ配信経路**を通ります。エンドポイントが受け入れなかった場合、その試行は自動試行と同様にレコードの
再試行予算から差し引かれ、次の自動再試行は予算が残っている間のみスケジュールされます。予算を使い切るとレコードは最終的に失敗となり、
**Next Retry** には `—` が表示され、以降の自動試行は行われません。

実務上のルール：**まずエンドポイントを検証し、その後に再送する。** まだ壊れているエンドポイントに再送すると、本来なら自動で
発火する予定だった試行を無駄に消費します。

## Portal は何を「Failed」レコードとみなしますか？

`Failed` は、最終的に失敗したレコードと、今回は失敗したがまだ自動再試行キューに残っているレコードの両方を含みます。
両者はステータスではなく **Next Retry** 列で区別されます。

| ステータス | Next Retry | 読み方 |
| - | - | - |
| Failed | タイムスタンプ | まだ自動再試行がスケジュールされている — そのままにしておいてよい |
| Failed | `—` | 再試行を使い切った。手動再送でのみ動く |
| Successful | `—` | 配信され、受け入れられた |

これは Retry by Date に関係します。見積もりは**両方**の種類の失敗レコードを数えるため、再送する期間には自然に回復したはずの
レコードが含まれることがあります。

## 成功したレコードに、エンドポイントからのレスポンスが表示されないのはなぜですか？

Portal は配信済みレコードの表示を、サーバーが送った内容を保存するのではなく導出しているためです。成功したレコードには
`200` の HTTP Response と `success` のボディが表示されますが、それは「成功」の定義がそうだからです — 配信が成功とみなされるのは、
[Webhook 概要](/docs/ja/developer-docs/webhook/overview) にあるとおり、エンドポイントが HTTP 200 **かつ** `{"message":"success"}` の
ボディを返した場合のみです。

実際に取得された詳細は**失敗した**レコードにのみ存在し、そこにはエンドポイントが返した失敗の概要 — またはトランスポートエラー —
が表示されます。したがって、デバッグ時に情報があるのは失敗したレコードです。成功したレコードの裏に隠れた追加情報はありません。

## 再送するとログに 2 行目が作成されますか？

いいえ。**ビジネスオブジェクトごと、イベントごとに 1 レコード**です — 同じ決済注文の決済通知は、その一生を通じて 1 行です。
再送はその行のステータス、レスポンス、試行回数をその場で更新し、行を追加しません。詳細ビューの **Notify Count** が試行履歴です。

これが、行数で配信量を測れない理由であり、再送されたレコードが後の試行で上書きされると以前の失敗概要を失う理由でもあります。

***

期待するレコードが失敗ではなく完全に欠落している場合は、
[Webhook イベントログと手動再送](/docs/ja/support/portal-webhook-log-faq) から始めてください — レコードの欠落はほぼ常に
コールバック URL が解決されなかったことを意味し、再送では解決できません。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.