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/order creation or transaction/order state change.

Webhook recipient configuration

Transaction recipients

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 for transaction events. 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"]
}

You can also list, retrieve or delete transaction recipients:

Endpoint	Description
GET List transaction recipients	List all transaction webhook recipients
GET Get a transaction recipient by ID	Retrieve a specific transaction webhook recipient
POST Create a transaction recipient	Register a new transaction webhook recipient
DEL Delete a transaction recipient	Remove a transaction webhook recipient

Order recipients

To set up an order webhook recipient, send a POST request to AddOrderWebhook endpoint. The request body must include the URL of the server where you want to receive the webhook notifications for order events (e.g. Autoswap conversions).

Example Request

HTTP

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

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

You can also list, retrieve or delete transaction recipients:

Endpoint	Description
GET List order recipients	List all order webhook recipients
GET Get an order recipient by ID	Retrieve a specific order webhook recipient
POST Create an order recipient	Register a new order webhook recipient
DEL Delete an order recipient	Remove an order webhook recipient

⚠️

URL must start with https://

Example 200 response (List recipients)

JSON

{
    "pagination": {
        "currentPage": 1,
        "totalPage": 1,
        "totalRecord": 1,
        "limit": 10
    },
    "data": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "url": "https://your-domain.com/webhook-endpoint",
            "createdAt": "2026-01-01T00:00:00Z",
            "updatedAt": "2026-01-01T00:00:00Z"
        }
    ]
}

---

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. Both transaction and order webhooks return only the eventType, status/newStatus, and the resource's id to get the full details (such as transaction type and subtype, or order details), call the corresponding Get by ID endpoint using the ID from the payload.

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>"
    }
  }
}

Possible newStatus values:

Status	Meaning
created	Transaction has been created
published	Transaction has been broadcast
mined	Transaction has been mined on-chain, pending confirmations
confirmed	Transaction has reached the required number of confirmations
failed	Transaction failed to process
declined	Transaction was declined
canceled	Transaction was canceled
dropped	Transaction was dropped from the network
expired	Transaction expired before completion

📘

To identify a transaction's type and subtype (Deposit, Internal Transfer, AutoSweep, AutoSwap, or Withdrawal), call Get Transaction by ID using the id from the webhook payload.

Order Created Event

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

JSON

{  
  "data": {
    "eventType": "order-created",
    "payload": {
      "id": "<order-id>",
      "orderReference":"<order-reference>"
    }
  }
}

Order Updated Event

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

JSON

{  
  "data": {
    "eventType": "order-updated",
    "payload": {
      "id": "<some-order-id>",
      "newStatus": "<new status>",
      "orderReference":"<order-reference>"
    }
  }
}

Possible newStatus values:

Status	Meaning
awaiting_funds	Order created, waiting for the deposit to be received
executed	Order has been executed
expired	Order expired before the deposit was received
failed	Order failed before completion

📘

To view an order's full details, call Get Order by ID using the id from the webhook payload.

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.