Webhook is not being delivered

What to check when a sale or order should have happened but no webhook reached your URL. First use a test send and the delivery log to tell whether ReceiptRoller did not send anything or sent it and your server failed it, then work through the causes for that case.

Check your server with a test send

curl -X POST https://receiptroller.io/api/v1/webhooks/test/{webhook_id} \
  -H "Authorization: Bearer {access_token}"

A test send goes out once, regardless of subscribed events or whether the webhook is switched on. The developer portal has no test button, so use the API.

Look at the delivery log

curl https://receiptroller.io/api/v1/webhooks/{webhook_id}/deliveries \
  -H "Authorization: Bearer {access_token}"

You get the latest 50 attempts, newest first. Whether there are rows around the time of the missing event decides where to look next.

• No rows: ReceiptRoller did not send it. See "No rows in the delivery log"
• Rows with success: false: it was sent and failed. Depending on httpStatus, see "Cannot connect" or "Your server rejects it"

No rows in the delivery log

• Is the webhook switched off? Check active in GET /api/v1/webhooks/{webhook_id}, or whether the app details page in the developer portal shows Inactive. Four failed attempts in a row switch it off, and nothing is sent while it is off. Once fixed, send { "active": true } with PATCH or use the resume button
• Are you subscribed to an event that is sent? Only receipt.created, order.created and order.updated are sent. receipt.updated, receipt.deleted, coupon.redeemed, coupon.expired and customer.visited can be subscribed to but are never sent
• Is it the right business account? A webhook receives events only from the business account it was registered for (through the API, the token's business account; in the portal, the business account that owns the app). Check organizationId in GET /api/v1/webhooks/{webhook_id}
• Does that action raise an event? receipt.created is sent only when a sale is saved for the first time. It is not sent when a POS resends the same sale, on a re-sync, when the same period's CSV is imported again, or for a deleted sale. Order events are sent when an order is created, edited, confirmed, started, cancelled or handed over at a POS in order management
• A restart on the ReceiptRoller side: pending retries are held on the server, so if it restarts while a retry is waiting, the remaining retries do not happen. The log then stops at a failed row. Fetch the missing period from the API

Cannot connect (httpStatus is 0)

errorMessage holds the reason.

• Is the URL reachable from the internet (not inside a corporate network or VPN, and the server is running)?
• Is the TLS certificate valid (not expired, not self-signed)?
• Is a firewall or WAF blocking outside POST requests?
• Does your server answer within 10 seconds? Move heavy work after the response (Designing resends, ordering, and idempotency)
• Did you change the URL's host or path? A registered URL cannot be changed, so register a new webhook for the new URL

Your server rejects it (4xx or 5xx)

• 401 / 403: usually a failed signature check
  • Are you using the secret from the webhook's registration (not the client secret)?
  • Are you computing over the raw body, before JSON parsing?
  • Are you comparing sha256= plus lower-case hex?
  • Webhooks registered before the fix of 23 October 2026 are signed with the app's client ID. Registering again gets you one signed with its secret
• 404 / 405: your routing does not accept a POST on that path
• 5xx: your processing errors. Look in your logs for the X-RR-Delivery received at that time

For details see Signature verification and security.

Recovering missed events

ReceiptRoller cannot resend past events. After fixing your server and switching the webhook back on, fetch the sales for the period you missed from the Transactions API.

Related guides

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