Webhookの概要

Webhook イベント API receipt.created order.created

Webhookは、ビジネスアカウントで売上や受注が発生したときに、レシートローラーがあなたのサーバーのURLへHTTPSでPOSTを送る仕組みです。この記事では、どのイベントが実際に送られるか、届くリクエストの形、配信で保証されることとされないこと、APIとの使い分けを説明します。

仕組み

  • Webhookは開発者アプリごとに登録し、受信URLと受け取りたいイベントを指定します。1つのアプリに複数のWebhookを登録できます
  • Webhookは1つのビジネスアカウントに結びつき、そのビジネスアカウントで起きたイベントだけが届きます
  • イベントが起きると、レシートローラーは購読しているすべての有効なWebhookへ、署名付きのJSONをPOSTします
  • 受信側が10秒以内に 2xx を返せば成功です。失敗すると1分後、10分後、1時間後に再送し、4回とも失敗するとそのWebhookは無効になります
  • デベロッパーAPIはスタータープラン以上で使えます

送信されるイベント

イベント 送られるとき data の中身
receipt.created 店舗の売上がレシートローラーに初めて保存されたとき（連携POS、決済端末、CSV取り込み）。1件の売上につき1回で、同じ売上の再送・再同期・再取り込みでは送られません。削除された売上では送られません 売上の要約（terminal_id、transaction_id、store_id、receipt_number、issued_at、status、total_amount、tax_amount、currency など）。顧客を特定する情報は含みません
order.created 受注管理で受注が作成されたとき 受注全体（order_id、order_number、status、total_amount、注文者名・連絡先・配送先、items_json など）
order.updated 受注が編集されたとき、または確認・処理開始・キャンセル・店舗POSでの受け渡しで状態が変わったとき 編集のときは受注全体。状態の変更のときは order_id、organization_id、status だけ（POSでの受け渡しでは linked_pos_terminal_id、linked_pos_transaction_id も）
test.ping テスト送信APIを呼んだときだけ { "message": "This is a test ping from Receipt Roller." }

receipt.updated、receipt.deleted、coupon.redeemed、coupon.expired、customer.visited も登録時に選べますが、現在は送信されません。これらを購読しても何も届きません。

receipt.created は売上の状態では絞り込まれません。初めて保存された取引が取消（Voided）や返品（Refunded）でも送られるので、売上だけを扱う場合は受信側で status を確認してください。

届くリクエスト

  • メソッドは POST、ボディはUTF-8のJSON（Content-Type: application/json）です
  • ボディのキーはすべてスネークケースです
ヘッダー 内容
X-RR-Signature sha256= に続けて、生のボディをWebhookのシークレットでHMAC-SHA256した小文字の16進文字列
X-RR-Event イベント名（例：receipt.created）
X-RR-Delivery イベントのID。ボディの id と同じ値で、再送でも変わりません

ボディは次の形です。

{
  "id": "evt_1a2b3c4d5e6f",
  "event": "receipt.created",
  "timestamp": "2026-10-26T03:15:43.1234567Z",
  "organization_id": "{organizationId}",
  "data": { ... }
}
  • id：イベントID（evt_ と12文字の16進数）。重複を除くキーに使います
  • event：イベント名
  • timestamp：レシートローラーがイベントを送り出した時刻（UTC）。再送でも同じ値です
  • organization_id：イベントが起きたビジネスアカウントのID
  • data：イベントごとの中身（上の表）

配信で保証されること・されないこと

  • 重複して届くことがあります。受信側が処理を終えたのに 2xx を返せなかった場合などに再送されます。X-RR-Delivery（＝ボディの id）で重複を除いてください
  • 順序は保証されません。イベントはそれぞれ独立に送られ、再送はあとから届きます。order.created より先に order.updated が届くこともあり得ます
  • 取りこぼしがあり得ます。再送の待ち時間はレシートローラーのサーバー上で保持されており、キューに保存されていません。その間にサーバーが再起動すると、残りの再送は行われません。また、Webhookが無効になっている間のイベントは保留されず、あとからまとめて届くこともありません
  • 過去のイベントを手動で再送する仕組みはありません

そのため、取りこぼしが許されない連携では、Webhookをきっかけとして使い、定期的にAPIで取り直して突き合わせる作りにしてください。

WebhookとAPIの使い分け

やりたいこと 使うもの
新しい売上や受注をすぐに知りたい Webhook
過去の売上を一覧で取得したい、日次で集計したい API（取引一覧API）
売上の明細や会員の情報も必要 Webhookで知り、terminal_id と transaction_id を手がかりにAPIで取得
売上の訂正や削除、クーポン利用、来店を知りたい API。これらのイベントはまだ送信されません
取りこぼしを確実に防ぎたい 両方。Webhookで即時に受け、APIで定期的に突き合わせる

関連ガイド

公開日: 2026-04-27 更新日: 2026-10-26
カテゴリ
すべて 一般 17 データ領域別ガイド 8 実装ガイド 7 Webhook 6 トラブルシューティング 6 APIの基本 5 アプリケーション登録 5 はじめに 4 運用とセキュリティ 4 認証とクレデンシャル 3
タグ
API (26) OAuth (21) Android (13) iOS (12) Webhook (9) api (6) oauth (5) クイックスタート (5) トラブル (5) Node.js (4)
関連記事