Create a webhook subscription to receive real-time notifications when events occur in your Lirium account.

Request

POST /webhooks/subscriptions

Request Body

Send one entry per event you want to receive. Each entry pairs an action with the URL that action is delivered to, so different events can go to different endpoints.

Subscribing an action that is already subscribed replaces its URL.

Supported Event Types

• order-closed - Order has been completed or cancelled
• order-updated - Order status has changed
• partner-order-created - Partner order has been created
• partner-order-closed - Partner order has been completed or cancelled
• partner-order-updated - Partner order status has changed
• customer-product-changed - The state of one of a customer's products has changed
• customer-requirement-rejected - Customer KYC requirement was rejected
• incoming-funds - Funds have been received at a receiving address

URL Requirements

The URL is validated when the subscription is created, and again before each delivery. It must:

• Use https.
• Have a host that resolves to a public address. Hosts resolving to private, loopback, link-local, reserved, multicast or unspecified addresses are rejected.
• Be resolvable at the time you subscribe.

⚠️

Local Endpoints Are Not Reachable

https://localhost and private-network hosts are rejected. To receive events on a local machine, expose it through a public tunnel and subscribe the tunnel's https URL.

Example Request

{
  "subscriptions": [
    {
      "action": "order-closed",
      "url": "https://your-server.com/webhooks/orders"
    },
    {
      "action": "customer-product-changed",
      "url": "https://your-server.com/webhooks/customers"
    }
  ]
}

Example Response

{
  "subscriptions": [
    {
      "action": "order-closed",
      "url": "https://your-server.com/webhooks/orders"
    },
    {
      "action": "customer-product-changed",
      "url": "https://your-server.com/webhooks/customers"
    }
  ]
}

Errors

{
  "error_code": "invalid_webhook_url",
  "error_msg": "Webhook url resolves to a disallowed address"
}

Security

All webhook calls include a JWT signature in the X-JWT-SIGNATURE header. See Webhooks Signature for verification details, and the Webhook Signature Verification recipe for a ready-to-use helper.

Your endpoint must:

• Use HTTPS
• Respond with a 2xx status code within 30 seconds
• Be idempotent (handle duplicate deliveries gracefully)

Deliveries do not follow redirects — subscribe the final URL rather than one that redirects to it.