How to register a Webhook
For developers of apps that use ReceiptRoller Webhooks. It explains the procedure from registering a Webhook endpoint in the developer portal to verifying connectivity with a test delivery.
To receive Webhooks, register a "Webhook endpoint" for your app in the developer portal. An endpoint is the URL that ReceiptRoller POSTs to when an event occurs. You can register multiple endpoints per app, so you can operate them separated by purpose and environment.
Prerequisites
- The app is registered in the developer portal (Creating a new app)
- You have a receiving server and an HTTPS URL ready
- You can safely store the secret for signature verification on the receiving side
Registration procedure
Step 1: Open the app's "Webhook" tab
Developer portal → app list → open the target app → click the "Webhook" tab at the top.
Step 2: Click "Add endpoint"
Pressing the "+ Add endpoint" button in the top-right opens the registration form.
Step 3: Fill in the required items
| Item | Required | Contents |
|---|---|---|
| Endpoint name | Required | A label for management. e.g. "Production - inventory sync" |
| URL | Required | https:// required. Query and fragment not allowed |
| Subscribed events | Required | Select the events you want to receive (multiple allowed) |
| Target store | Optional | Specify to narrow to specific stores only. Blank = all stores |
| Description | Optional | An operational memo. The purpose to share with the team |
| Enabled/disabled | Required | "Enabled" recommended at registration. Switch to "Disabled" to pause |
Step 4: Click "Create"
When registration completes, you move to the endpoint's detail screen. Here the secret for signature verification (Webhook Secret) is shown only once. Be sure to store it somewhere safe at this point.
How to choose subscribed events
We strongly recommend narrowing the events you subscribe to only the ones you need. The reasons are as follows.
- The receiving server's load decreases
- The processing logic becomes simpler (branches for unneeded events disappear)
- Noise during monitoring decreases
For example, if the purpose is "inventory sync", subscribe only to inventory.changed and inventory.low_stock, and do not subscribe to receipt.* or campaign.*. If you have multiple purposes, separating endpoints per purpose is cleaner operationally.
Test delivery
To confirm the registered endpoint can receive correctly, you can send a test event from the developer portal.
- Click the "Test delivery" button on the endpoint detail screen
- Select the event type you want to send
- Press "Send" to deliver a sample payload
- Check the receiving side's logs and response
The test-delivery payload includes a "test": true flag. If you do not want to route it to production processing on the receiving side, implement it to look at this flag and ignore it.
Using multiple endpoints
You can register up to 20 endpoints per app. Examples of common separations:
| Separation | Example |
|---|---|
| By environment | Production URL / staging URL / development URL |
| By purpose | For inventory sync / for accounting integration / for notifications |
| By store | When sending to a separate system per store |
| By priority | Separate real-time processing from audit-log storage |
Editing, disabling, and deleting
- Editing: the URL, subscribed events, target store, and description can be changed at any time. Reflected from the next delivery
- Disabling: you can pause with the "enabled/disabled" switch. Events that occur while stopped are not delivered (and not retained)
- Deleting: a full delete cannot be undone. Keeping the endpoint but disabling it is safer
Post-registration verification checklist
- ☐ The receiving URL is
https://and reachable from outside - ☐ You stored the Webhook Secret safely
- ☐ You implemented the signature verification logic
- ☐ You confirmed
2xxis returned in test delivery - ☐ You implemented the
event_id-based idempotency check - ☐ Your setup returns a response within 10 seconds
Related guides
-
Designing resends, ordering, and idempotencyExplains ReceiptRoller's Webhook resend policy, why delivery order is not guaranteed, implementing idempotency with event_id, handling dead letters, and common anti-patterns.
-
Webhook is not being deliveredHow to isolate the cause when a Webhook does not reach your receiving endpoint. Walks through checking, in order, the endpoint settings, subscribed events, reachability, signature-verification failures, and firewalls.
-
Developer Help IndexThe index of ReceiptRoller developer help. Covers the developer application, app registration, OAuth authentication and scopes, implementation guides (wallet apps, store-facing Webhooks, the Survey API), guides by data domain, operations and security, the community, and troubleshooting.
-
Monitoring and handling failuresExplains how to read the ReceiptRoller Webhook delivery history, the metrics to monitor and how to design alerts, redelivering dead letters, and common failure patterns and recovery procedures.
-
SNS Webhook bypass (forwarding Webhooks from external SNS such as LINE)Explains the mechanism, setup, signature handling, and cautions of the "SNS Webhook bypass" feature, which forwards Webhooks ReceiptRoller receives from SNS platforms such as LINE to a developer app, with the store's consent.