Webhooks
How a shop tells your app what happened, and what your app should answer.
Subscribing
Name the topics you want in your manifest, and the URL they are posted to:
[oauth]
scopes = ["orders:read"]
[webhooks]
url = "https://yourapp.example/webhooks"
events = ["order.paid.v1", "order.refunded.v1"]Every topic needs a scope that reads the same data, because an event is a read: order.created.v1 carries the buyer's email address. The event reference lists every topic and the scopes that cover it. An installation is only ever sent the events its grant covers.
Answering
- Answer 2xx within ten seconds. Anything else, a redirect included, is a failure, retried six times over about nine hours.
- Answer 401 to a signature that does not verify, so a misconfiguration shows in the merchant's delivery log. See Verifying requests.
- Answer topics you do not handle with a 200, not an error.
- Delivery is at least once and in no promised order. Key your work on the event, and read current state rather than adding up changes. See Payloads and delivery.
Events about your app
app.installed.v1, app.uninstalled.v1, app.scopes_changed.v1, app.release_approved.v1 and app.settings_updated.v1 go to your webhook URL whether or not you subscribe, and only to you. app.uninstalled.v1 arrives after the uninstall, when your tokens no longer work. The billing topics arrive the same way: see Charging merchants. For app.settings_updated.v1, see Settings.
compliance.customer_data_requested.v1, compliance.customer_redacted.v1 and compliance.store_redacted.v1 go to your [privacy] url. Act on them: they are how a shop meets its customers' rights. The merchant answers the request itself, so your app's token cannot export or erase a customer's data.
Trying one
Early access
npx @storeware/cli webhook trigger order.paid.v1Sends your app the latest real event of that topic from your development stores, signed as a delivery is.