Webhooks
Configure an endpoint
A webhook endpoint is a URL on your server that receives events. You add and manage endpoints in the dashboard.
Before you start#
- Build a route on your server that accepts
POSTrequests with a JSON body. See Receive events. - Decide which events you need. The event catalogue lists them.
The API has no endpoints to manage webhook endpoints. Use the dashboard.
Add an endpoint#
- Select the environment. In the dashboard, select sandbox or live. Each environment has its own endpoints and its own signing secrets.
- Enter the URL. Enter the full URL of your route, for example
https://shop.example.com/webhooks/merxian. - Select the events. Select at least one event type. Customer events are opt-in. The other events are selected by default for a new endpoint.
- Add a description. The description is optional. Use it to name the system that receives the events.
- Copy the signing secret. The dashboard shows the signing secret once. It starts with
whsec_. Store it in your secret store.
URL rules#
| Environment | Rules |
|---|---|
| Live | The URL must use https. The host must be a public address. Merxian does not deliver to private, loopback, or local addresses. A delivery to such an address fails at once. |
| Sandbox | The URL can use http or https. |
Use https in sandbox too, when you can. Then your sandbox setup is the same as your live setup.
Payload version#
When you create an endpoint, Merxian sets its payload version. The version is in the api_version field of every event and in the Merxian-Webhook-Version header. The current version is 2026-08-01.
The version of an endpoint does not change. See Versioning.
Manage endpoints#
In the dashboard, you can:
- List your endpoints and view one endpoint.
- Change the events that an endpoint receives.
- Delete an endpoint. Merxian stops sending events to it.
- Rotate the signing secret. See Rotate the secret.
The dashboard does not yet have a switch to pause an endpoint, a button to send a test event, a list of deliveries, or a way to send a delivery again.
Sandbox and live#
Sandbox and live are separate. An endpoint in sandbox receives only sandbox events. An endpoint in live receives only live events. Each endpoint has its own secret.
Before you go live, add a live endpoint and store its secret separately from the sandbox secret. See Go live.