Webhookの概要

Webhook イベント API リアルタイム連携

この記事の対象
レシートローラーのWebhookを初めて使う開発者向けです。Webhookとは何か、どのイベントが配信されるか、API（ポーリング）との使い分けを説明します。

Webhookは、レシートローラー側で「購買が成立した」「在庫が変動した」などのイベントが発生したときに、登録済みのURL（あなたのサーバー）に対してリアルタイムでHTTPSリクエストを送る仕組みです。アプリ側から定期的にAPIを叩く「ポーリング」と比較して、低レイテンシかつ無駄な通信が少なく、イベント駆動のシステム連携に向いています。

Webhook と API（ポーリング）の使い分け

用途	推奨	理由
購買発生をすぐ検知したい	Webhook	数秒以内に通知が届く
過去の購買を一覧で取得したい	API	ページネーション可能、再取得が容易
在庫変動に応じて即座に同期したい	Webhook	ポーリングより負荷が低い
日次バッチで集計したい	API	時刻指定で安定して取得できる
取りこぼしを完全に防ぎたい	両方併用	Webhookで即時、API再取得で補正

本番運用では Webhook + 定期的なAPI再取得 の併用が最も安全です。Webhookは原則として配信されますが、ネットワーク障害や受信側ダウンによる取りこぼしが完全にゼロとは限りません。

主なイベント種別

2026年4月時点で配信される主要なイベントは次のとおりです（カテゴリ別）。詳細はAPIリファレンス（Swagger）のWebhookセクションを参照してください。

購買・レシート系

receipt.issued — レシートが発行された
receipt.voided — レシートが取消された
receipt.refunded — 返金処理が行われた

商品・在庫系

product.created / product.updated / product.deleted
inventory.changed — 在庫数が変動した
inventory.low_stock — 在庫が閾値を下回った

キャンペーン・広告系

coupon.redeemed — クーポンが使用された
campaign.started / campaign.ended
ad.click — 広告がクリックされた（集計バッチで配信）

顧客・SNS系

customer.opted_in — マーケティング受信に同意
sns.post_published — SNS投稿が公開された

各イベントは、サブスクリプション登録時に「配信を受けたいイベント名」を選んで購読します。不要なイベントを購読しないことで受信側の負荷を抑えられます。

配信形式

Webhookは次の形式で配信されます。

メソッド：HTTPS POST（HTTPは不可）
Content-Type：application/json
本文：イベント情報を含むJSONペイロード
署名ヘッダー：X-RR-Signature（HMAC-SHA256）
イベントID：X-RR-Event-Id（冪等性キーとして利用）
タイムアウト：受信側は10秒以内に 2xx を返す必要あり

ペイロード例（receipt.issued）

{
  "event_id": "evt_01HV5K3M2N9PQR",
  "event_type": "receipt.issued",
  "occurred_at": "2026-04-27T10:15:23.000Z",
  "store_id": "str_abc123",
  "data": {
    "receipt_id": "rcp_xyz789",
    "total_amount": 3850,
    "currency": "JPY",
    "issued_at": "2026-04-27T10:15:22.500Z",
    "items_count": 4
  }
}

受信側は event_type で処理を分岐させ、data 内の各フィールドを使って自分のシステムを更新します。詳細データが必要な場合は、receipt_id を使ってAPIで本体を取得してください。Webhookペイロードには軽量なサマリーのみ含まれます。

配信保証の考え方

レシートローラーのWebhookは at-least-once（少なくとも1回） の配信保証です。つまり、同じイベントが2回以上届く可能性があります。受信側では event_id を使った冪等性の実装が必須です。

処理済みの event_id を保存し、重複を検知したら無視する
処理は冪等に書く（同じデータを2回適用しても結果が同じになるように）
順序は保証されません（後発のイベントが先に届く可能性あり）

詳細は再送・順序・冪等性の設計を参照してください。

料金とプラン

Webhookの利用にあたり、追加料金は発生しません。スタータープラン以上で利用できます。月間の配信件数および接続URLの数には公正利用ポリシーに基づく上限がありますが、通常の店舗運用範囲では制限に達することはありません。