Webhooks overview

What webhooks are for#

Many results in Merxian are not known when your API request returns. A buyer pays on the hosted page after you create the checkout session. A payment result comes from the payment network after some seconds, or later. A refund can succeed or fail after Merxian accepts it.

Merxian sends a webhook event for each of these changes. Your webhook endpoint receives the event and updates your system.

How delivery works#

1. Your server sends an API request, for example to create a checkout session.
2. Merxian returns the created resource.
3. When the resource changes, Merxian sends a POST request with the event to your endpoint. The request is signed.
4. Your endpoint verifies the signature and returns a 2xx status within 10 seconds.
5. Your system acts on the event, for example it fulfils the transaction.

If your endpoint does not return a 2xx status, Merxian tries again later. See Delivery and retries.

When to rely on events#

Use webhook events for these results:

The event catalogue lists every event.

The event envelope#

Every event has the same envelope. The resource is in data.object.

{
  "id": "whevt_7Kd2VpXn4TqB9mLzR",
  "object": "event",
  "type": "payment.succeeded",
  "created_at": "2026-09-14T09:24:53Z",
  "api_version": "2026-08-01",
  "account_id": "acct_5Rn8bQ2xW7mK4tLzP",
  "data": {
    "object": {
      "id": "pay_3RtN6wYc8mK2hQvJd",
      "object": "payment",
      "status": "succeeded",
      "transaction_id": "txn_0F8mQ2rXbT4kL9pZa",
      "amount": 14280,
      "currency": "EUR"
    }
  }
}

The amount 14280 in EUR is €142.80. The example shows only some fields of the payment. Receive events describes each envelope field.

Webhook payloads use snake_case field names. The API uses camelCase. Some state values also differ from the API values. See State values in payloads.

What you must build#

• An HTTPS endpoint on your server that accepts POST requests. See Configure an endpoint.
• Signature verification for every request. See Verify signatures.
• Idempotent processing by event ID, because an event can arrive more than once. See Process events.
• Processing that does not depend on the order of events.