Webhooks push data to your server as soon as a record changes, instead of polling the Open API.
Configuration
Configure webhooks in Settings › Apps › Webhook/API, Webhook URL tab, or through the Webhook configuration API:
| Setting | Meaning |
|---|---|
| Webhook URL | Your public https:// address, required |
| Error email | Receives an email when a delivery fails |
| Headers | Headers sent with every request, for example a secret your server checks to verify the sender |
| Data types | One or more of the types below |
Data types
| Type | Sent when | Payload |
|---|---|---|
orders |
An order is created or updated | WebhookOrderResponse |
customers |
A customer is created or updated | WebhookCustomerResponse |
products |
A product is created or updated | WebhookProductResponse |
variations_warehouses |
A variation's stock changes | WebhookInventoryResponse |
auto_call |
An automated call ends | WebhookAutoCallResponse |
Receiving webhooks
POS sends a POST with a JSON body and your configured headers. Your server should:
- Return a
2xxstatus within 30 seconds. Any other status or a timeout counts as a failure. - Do heavy work (calling other systems, writing many tables) on a separate queue and return
2xxfirst. - Check the secret header you configured so it only accepts requests from POS.
- Accept the same record more than once (after retries or rapid successive changes): use the record ID and update time to skip stale versions.
Retries on failure
- When the first delivery fails: POS emails the error address (if set), retries after 10 minutes, then again 30 minutes later, then stops.
- When your server keeps failing: POS pauses deliveries to avoid piling up load, then resumes once your server responds normally.
- When the URL is invalid: POS turns the shop's webhook off. Fix the URL and turn it back on.
To recover data missed while your server was down, read it back through the Open API filtered by update time (see Pagination).