Webhooks

Webhooks are a powerful feature that enables you to stay up-to-date with events in Waltrex without the need for constant polling. Instead, we send data directly to your application when relevant events occur, such as transaction creation or transaction state change.

Webhook recipient configuration

To set up a webhook recipient, send a POST request to AddWebhook endpoint. The request body must include the URL of the server where you want to receive webhook notifications. This is the destination that will receive HTTP requests (webhook events) whenever specific actions occur in your account (such as transactions, updates, or system events).

Example Request

HTTP

POST /webhooks/private/v1/recipients HTTP/1.1
Host: api.stage.waltrex.io
Content-Type: application/json

{
  "urls": ["https://your-endpoint-url.com/webhooks"]
}

Webhook Event Payload

When an event occurs, the system sends a POST request to your configured endpoint, including a JSON payload. The structure of the payload varies based on the event type.

Transaction Created Event

When a transaction is created, you will receive a webhook with the following payload:

JSON

{  
  "data": {
    "eventType": "transaction-created",
    "payload": {
      "id": "<tx-id>"
    }
  }
}

Transaction Updated Event

When a transaction is updated, you will receive a webhook with the following payload:

JSON

{  
  "data": {
    "eventType": "transaction-updated",
    "payload": {
      "id": "<some-tx-id>",
      "newStatus": "<new status>"
    }
  }
}

Webhook Retry Policy

The system ensures failed webhooks are retried with increasing delays, capped at 30 minutes, with up to 5 total attempts before permanent failure.

Webhook Response

The webhook endpoint is expected to respond with HTTP 200 OK response to confirm the webhook event was received.