Webhook 的概要

Webhook 事件 API 即時串接

本文的對象
適用於初次使用 ReceiptRoller 的 Webhook 的開發者。說明 Webhook 是什麼、會投放哪些事件、與 API（輪詢）的分別使用。

Webhook 是在 ReceiptRoller 端「購買成立了」「庫存變動了」等事件發生時，對已登錄的 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 酬載中僅含輕量的摘要。

投放保證的思考方式

ReceiptRoller 的 Webhook 是 at-least-once（至少 1 次） 的投放保證。也就是說，同一事件有可能送達 2 次以上。接收端以 event_id 進行的冪等性的實作為必須。

保存已處理的 event_id，偵測到重複則忽略
將處理冪等地寫入（讓同一資料套用 2 次結果也相同）
順序不被保證（後發的事件可能先到達）

詳情請參照重送、順序、冪等性的設計。

費用與方案

使用 Webhook 時不發生追加費用。在 Starter 方案以上可利用。每月的投放件數以及連接 URL 的數量有基於公正利用政策的上限，但通常的店鋪運用範圍不會達到限制。