Webhook overview

A Webhook is a mechanism where, when an event such as "a purchase was completed" or "stock changed" occurs on the ReceiptRoller side, it sends an HTTPS request in real time to a registered URL (your server). Compared to "polling" — hitting the API periodically from the app side — it has lower latency and less wasted communication, and is well suited to event-driven system integration.

When to use Webhook vs. the API (polling)

In production, combining Webhook + periodic API re-fetch is the safest. Webhooks are delivered as a rule, but missed data due to a network failure or a receiving-side outage is not guaranteed to be strictly zero.

Main event types

The main events delivered as of April 2026 are as follows (by category). For details, see the Webhook section of the API reference (Swagger).

Purchase / receipt

• receipt.issued — a receipt was issued
• receipt.voided — a receipt was voided
• receipt.refunded — a refund was processed

Product / inventory

• product.created / product.updated / product.deleted
• inventory.changed — the stock count changed
• inventory.low_stock — stock fell below the threshold

Campaign / advertising

• coupon.redeemed — a coupon was used
• campaign.started / campaign.ended
• ad.click — an ad was clicked (delivered in aggregated batches)

Customer / SNS

• customer.opted_in — consented to receive marketing
• sns.post_published — an SNS post was published

You subscribe to each event by choosing the "event names you want to receive" at subscription registration. Not subscribing to unneeded events keeps the receiving side's load down.

Delivery format

Webhooks are delivered in the following format.

• Method: HTTPS POST (HTTP not allowed)
• Content-Type: application/json
• Body: a JSON payload containing the event info
• Signature header: X-RR-Signature (HMAC-SHA256)
• Event ID: X-RR-Event-Id (used as the idempotency key)
• Timeout: the receiving side must return 2xx within 10 seconds

Payload example (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
  }
}

The receiving side branches processing on event_type and updates its own system using the fields inside data. If you need detailed data, use the receipt_id to fetch the full record via the API. The Webhook payload contains only a lightweight summary.

How to think about delivery guarantees

ReceiptRoller Webhooks have an at-least-once delivery guarantee. That is, the same event may arrive two or more times. On the receiving side, implementing idempotency using event_id is essential.

• Save processed event_ids and ignore duplicates when detected
• Write processing idempotently (so that applying the same data twice produces the same result)
• Order is not guaranteed (a later event may arrive first)

For details, see Designing resends, ordering, and idempotency.

Pricing and plans

There is no additional charge to use Webhooks. They are available on the Starter plan or higher. The number of monthly deliveries and the number of connection URLs have limits based on a fair-use policy, but a normal store operation will not hit them.

Related guides

• How to register a Webhook
• Signature verification and security
• Designing resends, ordering, and idempotency
• Monitoring and handling failures
• Back to the developer help index