Webhook Setup

Setting Up a Webhook

To setup a webhook it is needed to have an already created webhook endpoint in your application.

To configure a webhook, use the Create Webhook endpoint. Specify the transaction states for which the webhook should trigger and provide the destination URL where the request payload will be sent.

When a transaction undergoes processing, each step generates an event that is converted into a request and sent to the webhook's designated URL.

The destination URL is determined based on the webhook configuration created for the merchant or the notifyUrl provided in the transaction during its creation. If both are specified, the notifyUrl takes precedence, and all requests will be directed to it.

Delivery Behavior

If the response to a webhook request does not return a status code of 200 (OK) or 204 (No Content), the webhook entry is marked as failed. Failed requests will be retried every 30 minutes, up to a maximum of 48 attempts over 24 hours. If delivery remains unsuccessful after this period, the entry is marked as cancelled.

Example Webhook Payload

{
  "transactionId": "9e9e3f2c-5d88-410e-80b5-f4389c284b15",
  "shortId": "250101XMMSFE8U",
  "createdAt": "2025-01-01T00:00:00.000000Z",
  "amount": {
    "value": 10000.00,
    "currency": "EUR"
  },
  "status": "COMPLETED",
  "type": "TRANSFER",
  "tenantId": "8c5955e2-03c1-463c-a6ba-6d8a85e2e131",
  "merchantId": "405a6e39-0fcb-4bbd-bd24-0a3540b44eb2",
  "sourceAccountId": "27bb9d34-b78d-464a-873e-b87516451be0",
  "destinationAccountId": "a3fceb93-0d8d-4759-8e57-ec55230db89c",
  "sourceAccount": {
    "accountId": "27bb9d34-b78d-464a-873e-b87516451be0",
    "name": "EUR account 1",
    "accountFor": "TRADING",
    "type": "USER",
    "currency": "EUR",
    "currencyType": "FIAT"
  },
  "destinationAccount": {
    "accountId": "a3fceb93-0d8d-4759-8e57-ec55230db89c",
    "name": "EUR account 2",
    "accountFor": "TRADING",
    "type": "USER",
    "currency": "EUR",
    "currencyType": "FIAT"
  },
  "notifyUrl": "http://example.com",
  "related": true,
  "feeAmount": {
    "value": 0.00,
    "currency": "EUR"
  },
  "feeAccountId": "27bb9d34-b78d-464a-873e-b87516451be0",
  "feeFromAmount": false
}