Access and setup
Webhooks are configured in the admin panel. Access belongs to the shop administrator; no separate API token is needed for the setup. Your job as a developer is to prepare a handler URL, pass it to the administrator (or configure it yourself if you have admin access) and store the signing secret.
Where it lives
Open Settings, Data exchange, the Webhooks tab. It holds two inner tabs:
- Events: the list of all events and the subscriptions to them.
- Log: the delivery history (see Usage).
Subscribing to an event
In the event table each row is one event. To subscribe, press Configure (or Edit if a subscription already exists) and fill in:
| Field | Description |
|---|---|
| Subscriber URL |
The address requests are sent to. It must start with http:// or https://. For production use https:// only. |
| Timeout (ms) | How long to wait for your server. At least 500 ms. The maximum depends on the mode: 30,000 ms for sync, 300,000 ms for async. |
| Retries on error | How many times to retry an async delivery on error (0 to 10). Sync events are not retried. |
| Description | An internal note for administrators: where the webhook goes and why. |
| Active | Switched off, the configuration is kept but events are not sent. |
A default timeout is filled in automatically: 5,000 ms for most sync events,
2,000 ms for catalog.bonus.calculate (catalogue listing is speed-critical) and
60,000 ms for async events.
The signing secret
Every subscription signs its requests (HMAC-SHA256). The secret lets you verify the authenticity of a request on your side, see Verifying the signature.
- When a subscription is created, the secret is generated automatically and shown once: copy it straight away.
- Later the secret can be viewed with the Secret action in the event row.
- To replace the secret, tick Generate a new secret while editing. After rotation the old secret stops working: update it on your side.
Testing a webhook
The Test button in an event row sends a test request to your URL and shows the result: the HTTP status and the response time. Use it to make sure your handler is reachable and verifies the signature correctly, before any real events.
Deleting a subscription
The Delete button removes the subscription to an event. The configuration and the secret are deleted; events stop being sent to that address.
Related pages
- Usage: the request envelope, signature verification, the response contract.
- Webhooks overview
- OpenAPI documentation: the event field schemas.