Handle Webhook Events

Once you've set up a webhook, Lydian delivers events to your endpoint as an HTTP POST with a JSON body. This guide covers how to receive and process them.

The event envelope

Every event is delivered as the same JSON envelope:

envelope

{
  "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
  "type": "transaction.success",
  "timestamp": "2025-08-15T10:15:44.762134-04:00",
  "data": { }
}
  • accountUUID — the account the event belongs to.
  • type — the event type (see below).
  • timestamp — when the event was emitted.
  • data — the event-specific payload. For payment events, data is the full transaction record — the same shape as the Get Transaction Response.

Process an event

  1. Receive the POST at your configured endpoint and read the JSON body.
  2. Inspect type to decide how to handle the event.
  3. Read data for the details — for a payment event, data.status of 1 means the transaction succeeded.
  4. Respond quickly with a 2xx so Lydian considers delivery successful; do heavier work asynchronously.
  5. Make handlers idempotent. The same event may be delivered more than once, so key your processing on a stable identifier (such as the transactionID in data) and ignore duplicates.

For anything that moves money or fulfills an order, confirm the current state against the API — call GET /transaction/{transactionID} — rather than trusting the payload alone.

Event types

For the currently documented webhook event types and payloads, see Event Payloads.

For the transaction.success and transaction.failed payment events, data is the full transaction object, with status reflecting the outcome (for example 1 succeeded, or -2 cancelled / -4 forfeited on failure).