Webhook
HTTPSエンドポイントへのイベント送信です。配信レシート、着信メッセージ、ステータスの変更を送り、受信側は検証、迅速な応答、キューへの登録を行う必要があります。
定義のみです。ここで説明する用語は、当社が販売するサービスではありません。
Webhookは、登録したURLにイベントをPOSTするHTTPSコールバックです。送られるイベントには、配信レシートや着信メッセージなどがあります。受信側は署名を検証し、2xxで応答し、処理をキューに登録します。
受信側は重複したイベントや順序が入れ替わったイベントを処理します。Webhookはプッシュ型の配信です。
検証、応答、キュー登録
イベントが発生すると、プロバイダーがPOSTを送信し、お客様のエンドポイントは2xxを返して受信を確認します。ペイロードは通常JSONで、イベントの種類と識別子を含みます。プロバイダーがペイロードに署名する場合は、共有シークレットを使って生のボディと署名を照合し、リプレイウィンドウ外のリクエストは拒否してください。
まず検証し、生のイベントを保存し、2xxを返してから、処理を非同期で行ってください。エンドポイントの応答が遅いと再送が発生します。配信は通常at-least-once（少なくとも一度）で、順序は保たれないため、イベントIDで重複を排除してください。処理できないイベントにはデッドレターキューを用意してください。SMPPとHTTPの比較では、コールバックとセッションベースの配信を比較しています。
よくある質問
WebhookとAPIの違いは何ですか。
APIは通常、クライアントがプルします。Webhookはイベントが発生したときにプロバイダーがプッシュします。ほとんどのプラットフォームは両方を提供しています。
イベントが2回届くのはなぜですか。
配信は通常at-least-once（少なくとも一度）であるため、再送によって処理済みのイベントが重複することがあります。イベントIDで重複を排除してください。
どのステータスを返すべきですか。
イベントを永続化またはキューに登録した時点で2xxを返してください。それより前に2xxを返すと、次の処理が失敗したときにイベントを失うおそれがあります。