> Lydian Developer Documentation > Page: https://developer.lydian.com/api/webhooks/events > Documentation index: https://developer.lydian.com/llms.txt # Webhook Events This page describes the payloads Lydian delivers to your webhook endpoints. To register an endpoint, see [Webhooks](https://developer.lydian.com/api/webhooks.md). For guidance on receiving and processing events, see [Handle Webhook Events](https://developer.lydian.com/guides/handle-webhook-events.md). ## The Event Envelope Every webhook — regardless of type — is delivered as the same JSON envelope over an HTTP `POST` with `Content-Type: application/json`. The envelope identifies the event and the account it belongs to, while the event-specific details live in the `data` object. - `accountUUID` (string): UUID of the account the event belongs to. - `type` (string): The event type — see [Event Types](#event-types) below. - `timestamp` (string): RFC 3339 timestamp of when the event was emitted. - `data` (object): The event payload. Its structure depends on `type`. **envelope** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "transaction.success", "timestamp": "2025-08-15T10:15:44.762134-04:00", "data": { } } ``` > **Note:** Timestamps in webhook payloads are RFC 3339 strings. Some use UTC (`Z`) and others a numeric offset such as > `-04:00`, so parse the offset rather than assuming every timestamp ends in `Z`. ## Event Types A webhook only receives the event types it subscribed to when it was created (the `events` array — see [Create Webhook](https://developer.lydian.com/api/webhooks.md#create-webhook)). The event types currently documented are listed below; treat this as the currently documented set rather than a guaranteed-exhaustive catalog: | `type` | Sent when | | --------------------------------- | ---------------------------------------------------------------------------- | | `transaction.success` | A transaction is fully paid and confirmed on-chain. | | `transaction.failed` | A transaction fails or is cancelled before it completes. | | `refund.success` | A refund has completed successfully. | | `refund.failed` | A refund has failed. | | `session.promoted` | A session has been promoted and a transaction is being created. | | `session.canceled` | A session has been canceled and is no longer active. | | `session.timedout` | A session has timed out and is no longer active. | | `settlement.closed` | A settlement period has ended and the net amount owed to you is final. | | `settlement.paid` | The settlement's funds have been sent to your registered payout destination. | | `reconciliation_report.generated` | A daily reconciliation report has been generated for your account. | ## transaction.success Sent when a transaction has been fully paid and confirmed. The `data` object is the complete transaction record — identical in structure to the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response). A successful transaction has `status` `1` and no remaining balance. - `data` (object): The full transaction object. See the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response) for the complete field list. **transaction.success** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "transaction.success", "timestamp": "2025-08-15T10:15:44.762134-04:00", "data": { "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a", "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99", "externalMID": "", "descriptor": "Order #1234", "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51", "status": 1, "paymentStatus": 1, "amounts": { "currency": "USD", "totalLocal": 9.34, "totalUSD": 9.34, "receivedUSD": 9.34, "customerFeeUSD": 1.25, "fxRateToUSD": 1 }, "compliance": { "kycTriggered": false, "travelRuleTriggered": false }, "payments": [ { "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab", "cryptoAsset": "USDT", "cryptoNetwork": "ethereum", "cryptoRatePerUSD": 1, "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd", "walletName": "metamask", "walletType": "non-custodial", "expectedCrypto": 9.34, "receivedCrypto": 9.34, "expectedUSD": 9.34, "receivedUSD": 9.34, "txnHash": "0x9f2c...c4dd", "fromAddress": "0x3a1f9c8b7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b", "confirmationCount": 12, "completedAt": "2025-08-12T03:21:40.512Z", "gasFee": 0.42, "gasFeeUnits": "ETH", "status": 1, "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd", "expiration": "2025-08-12T03:35:02.769Z" } ], "refunds": [], "remainingLocal": 0, "remainingUSD": 0, "cancellationReason": "", "createdAt": "2025-08-12T03:20:02.769Z", "updatedAt": "2025-08-12T03:21:44.762Z", "expiration": "2025-08-12T03:35:02.769Z" } } ``` ## transaction.failed Sent when a transaction fails or is cancelled before it completes. The `data` object has the same structure as [`transaction.success`](#transaction-success) — the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response) — with the transaction's `status` reflecting the failure (for example `-2` cancelled or `-4` forfeited) and `cancellationReason` set where applicable. - `data` (object): The full transaction object, with `status` reflecting the failure. See the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response) for the complete field list and the full set of status values. **transaction.failed** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "transaction.failed", "timestamp": "2025-08-15T10:22:03.114902-04:00", "data": { "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a", "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99", "descriptor": "Order #1234", "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51", "status": -2, "paymentStatus": 0, "amounts": { "currency": "USD", "totalLocal": 9.34, "totalUSD": 9.34, "receivedUSD": 0, "customerFeeUSD": 1.25, "fxRateToUSD": 1 }, "payments": [ { "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab", "cryptoAsset": "USDT", "cryptoNetwork": "ethereum", "cryptoRatePerUSD": 1, "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd", "walletName": "metamask", "walletType": "non-custodial", "expectedCrypto": 9.34, "receivedCrypto": 0, "expectedUSD": 9.34, "receivedUSD": 0, "txnHash": "", "fromAddress": "", "confirmationCount": 0, "completedAt": "0001-01-01T00:00:00Z", "gasFee": 0, "gasFeeUnits": "", "status": 0, "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd", "expiration": "2025-08-12T03:35:02.769Z" } ], "remainingLocal": 9.34, "remainingUSD": 9.34, "cancellationReason": "Payment window expired", "createdAt": "2025-08-12T03:20:02.769Z", "updatedAt": "2025-08-12T03:35:02.769Z", "expiration": "2025-08-12T03:35:02.769Z" } } ``` ## refund.success Sent when a refund completes successfully. The `data` object is the refund payload; a successful refund has `status` `1`. - `createdAt` (string): Timestamp when the refund record was created. - `updatedAt` (string): Timestamp when the refund was last updated. - `refundID` (string): Unique identifier for the refund. - `transactionID` (string): Identifier of the transaction associated with the refund. - `paymentRequestID` (string): Identifier of the payment request associated with the refund. - `accountID` (string): Identifier of the account associated with the refund. - `merchantID` (string): Identifier of the merchant associated with the refund. - `referenceNumber` (string): Merchant reference or order number of the refunded transaction. May be an empty string. - `origin` (string): What initiated the refund. One of `merchant`, `fraud`, or `cancellation`. - `reason` (string): Reason for the refund. May be an empty string. - `status` (integer): Refund status: `-1` failed, `0` pending, `1` success. - `stage` (string): Current stage of the refund. One of `queued`, `sending`, `swapping`, `confirming`, or `done`. - `route` (string): Refund processing route. One of `direct`, `swap`, or `custody`. - `custody` (string): Custody provider, when applicable. One of `bitgo` or `maya`. Optional. - `custodyRef` (string): Custody provider reference, when applicable. Optional. - `failureReason` (string): Details about a failure, when present. May be an empty string. - `fiatCurrency` (string): Fiat currency of the refund (for example `USD`). - `fiatAmount` (number): Fiat amount refunded. - `gasFeePayer` (string): Who absorbs the network gas fee. One of `merchant` or `customer`. - `receiverAddress` (string): Destination wallet address for the refund. May be an empty string. - `cryptoAsset` (string): Crypto asset returned (for example `USDT`). - `cryptoNetwork` (string): Network the refund is delivered on (for example `arbitrum`). - `fiatFXRate` (number): Fiat-to-USD exchange rate for the refund. - `usdAmount` (number): USD value of the refund. - `sourceFXRate` (number): Source exchange rate stored for the refund. - `sourceAmount` (number): Source amount stored for the refund. - `sourceUSD` (number): Source-side USD value for the refund. - `sourceTxHash` (string): Source transaction hash. May be an empty string. - `swapID` (string): Swap identifier, when present. Optional. - `swapPayinAddress` (string): Swap pay-in address, when present. Optional. - `swapQuotedAmount` (number): Quoted swap amount. - `cryptoAmount` (number): Crypto amount returned. - `deliveryTxHash` (string): Delivery transaction hash. May be an empty string. - `initiatedAt` (string): Timestamp when the refund was initiated. - `executedAt` (string): Timestamp when the refund was executed. **refund.success** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "refund.success", "timestamp": "2025-08-15T10:22:14.512402-04:00", "data": { "createdAt": "2025-08-15T10:20:02.769Z", "updatedAt": "2025-08-15T10:22:14.512Z", "refundID": "acd09ac7-612f-4011-ac74-a5e1f4753648", "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a", "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab", "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99", "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51", "origin": "merchant", "reason": "Customer requested a refund", "status": 1, "stage": "done", "route": "direct", "failureReason": "", "fiatCurrency": "USD", "fiatAmount": 9.34, "gasFeePayer": "customer", "receiverAddress": "", "cryptoAsset": "USDT", "cryptoNetwork": "arbitrum", "fiatFXRate": 1, "usdAmount": 9.34, "sourceFXRate": 0, "sourceAmount": 0, "sourceUSD": 0, "sourceTxHash": "", "swapQuotedAmount": 0, "cryptoAmount": 9.34, "deliveryTxHash": "0x9f2c...c4dd", "initiatedAt": "2025-08-15T10:20:03.114Z", "executedAt": "2025-08-15T10:22:14.500Z" } } ``` ## refund.failed Sent when a refund fails. The `data` object has the same structure as [`refund.success`](#refund-success), with `status` `-1` and `failureReason` set when a reason is available. - `data` (object): The refund object, with `status` `-1`. See [`refund.success`](#refund-success) for the complete field list. **refund.failed** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "refund.failed", "timestamp": "2025-08-15T10:23:41.882013-04:00", "data": { "createdAt": "2025-08-15T10:20:02.769Z", "updatedAt": "2025-08-15T10:23:41.880Z", "refundID": "acd09ac7-612f-4011-ac74-a5e1f4753648", "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a", "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab", "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99", "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51", "origin": "merchant", "reason": "Customer requested a refund", "status": -1, "stage": "done", "route": "direct", "failureReason": "destination wallet rejected the transfer", "fiatCurrency": "USD", "fiatAmount": 9.34, "gasFeePayer": "customer", "receiverAddress": "", "cryptoAsset": "USDT", "cryptoNetwork": "arbitrum", "fiatFXRate": 1, "usdAmount": 9.34, "sourceFXRate": 0, "sourceAmount": 0, "sourceUSD": 0, "sourceTxHash": "", "swapQuotedAmount": 0, "cryptoAmount": 9.34, "deliveryTxHash": "0x9f2c...c4dd", "initiatedAt": "2025-08-15T10:20:03.114Z", "executedAt": "2025-08-15T10:22:14.500Z" } } ``` ## session.canceled Sent when a session has been canceled. The `data` object is the session's [Create Session](https://developer.lydian.com/api/session.md#create-session) response. - `sessionID` (string): Unique identifier for the session. - `qrData` (string): The data to generate a QR code that can be scanned using mobile devices. - `cancelURL` (string): Redirect URL used when the session is cancelled. - `successURL` (string): Redirect URL used on a successful payment. - `failureURL` (string): Redirect URL used on a failed payment. - `fiatFXRate` (number): The fiat FX rate locked in for the session when provided; `null` otherwise. - `recommendedNetwork` (string): Network recommended to the customer at checkout, when provided. - `quoteID` (string): Quote identifier associated with the session, when provided. - `merchantName` (string): Name of the merchant the session belongs to. - `referenceNumber` (string): Merchant reference or order number for the session. Optional; omitted when not set. **session.canceled** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "session.canceled", "timestamp": "2025-08-15T10:15:44.762134-04:00", "data": { "sessionID": "009a3809-7328-4b6c-873b-089eff019f98", "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98", "cancelURL": "https://brimspire.com/checkout/cancel", "successURL": "https://brimspire.com/checkout/success", "failureURL": "https://brimspire.com/checkout/failure", "fiatFXRate": 1, "recommendedNetwork": "ethereum", "quoteID": "", "merchantName": "Brimspire" } } ``` ## session.promoted Sent when a session has been promoted. The `data` object has the same structure as [`session.canceled`](#session-canceled). - `data` (object): The session object. See [`session.canceled`](#session-canceled) for the complete field list. **session.promoted** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "session.promoted", "timestamp": "2025-08-15T10:15:44.762134-04:00", "data": { "sessionID": "009a3809-7328-4b6c-873b-089eff019f98", "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98", "cancelURL": "https://brimspire.com/checkout/cancel", "successURL": "https://brimspire.com/checkout/success", "failureURL": "https://brimspire.com/checkout/failure", "fiatFXRate": 1, "recommendedNetwork": "ethereum", "quoteID": "", "merchantName": "Brimspire" } } ``` ## session.timedout Sent when a session has timed out. The `data` object has the same structure as [`session.canceled`](#session-canceled). - `data` (object): The session object. See [`session.canceled`](#session-canceled) for the complete field list. **session.timedout** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "session.timedout", "timestamp": "2025-08-15T10:15:44.762134-04:00", "data": { "sessionID": "009a3809-7328-4b6c-873b-089eff019f98", "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98", "cancelURL": "https://brimspire.com/checkout/cancel", "successURL": "https://brimspire.com/checkout/success", "failureURL": "https://brimspire.com/checkout/failure", "fiatFXRate": 1, "recommendedNetwork": "ethereum", "quoteID": "", "merchantName": "Brimspire" } } ``` ## settlement.closed Sent when a settlement period ends. The `data` object is the settlement record: the period it covers, its `status` (`1` = closed), and `netUSD`, the amount owed to you for that period after fees. `merchantID` is present when the settlement is for a single merchant rather than the whole account. There is no `payout` yet. - `settlementID` (string): Unique identifier for the settlement. - `accountID` (string): UUID of the account being settled. - `merchantID` (string): UUID of the merchant being settled. Omitted when the settlement covers the whole account. - `status` (integer): Settlement status. `1` means closed and `3` means paid. - `frequency` (string): Settlement schedule: `hourly`, `six_hourly`, `daily`, `weekly`, `biweekly`, or `monthly`. - `periodStart` (string): RFC 3339 start of the settled period (inclusive). - `periodEnd` (string): RFC 3339 end of the settled period (exclusive). - `netUSD` (number): Amount owed to you for the period, in USD, after fees. - `payout` (object): Present once funds have been sent. See settlement.paid below. **settlement.closed** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "settlement.closed", "timestamp": "2026-09-07T00:00:04.118273Z", "data": { "settlementID": "3f0c9a4e-7d1b-4c2a-9e58-1b6f0d2a7c11", "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99", "status": 1, "frequency": "daily", "periodStart": "2026-09-06T00:00:00Z", "periodEnd": "2026-09-07T00:00:00Z", "netUSD": 97.5 } } ``` ## settlement.paid Sent when the settlement's funds have been sent to your registered payout destination and, for crypto destinations, confirmed on-chain. The `data` object has the same structure as [`settlement.closed`](#settlement-closed) with `status` `3` and a `payout` object describing the transfer. - `payout` (object): The transfer that paid this settlement. **Payout Object** - `type` (string): Destination type: `crypto_wallet` or `bank_account`. - `initiatedAt` (string): RFC 3339 timestamp of when the transfer was initiated. - `confirmedAt` (string): RFC 3339 timestamp of when the transfer was confirmed. - `cryptoWallet` (object): Present for crypto destinations: `network`, `asset`, `destinationAddress`, and the on-chain `txnHash`. **settlement.paid** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "settlement.paid", "timestamp": "2026-09-07T01:05:12.331901Z", "data": { "settlementID": "3f0c9a4e-7d1b-4c2a-9e58-1b6f0d2a7c11", "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99", "status": 3, "frequency": "daily", "periodStart": "2026-09-06T00:00:00Z", "periodEnd": "2026-09-07T00:00:00Z", "netUSD": 97.5, "payout": { "type": "crypto_wallet", "initiatedAt": "2026-09-07T01:00:03.502Z", "confirmedAt": "2026-09-07T01:05:12.117Z", "cryptoWallet": { "network": "arbitrum", "asset": "USDT", "destinationAddress": "0x1c9a3b7f2e5d4c6b8a0f9e8d7c6b5a4f3e2d1c0b", "txnHash": "0x9f2c...c4dd" } } } } ``` ## reconciliation\_report.generated Sent when Lydian generates a daily reconciliation report for your account. Each report covers one calendar day in your account's local time zone (UTC if none is set) and lists the confirmed payments of transactions settled during that day. Reports are generated about an hour after the day ends, including for days with no payments (`rowCount` `0`). The `data` object describes the generated report file. - `reportID` (string): Unique identifier for the report. - `type` (string): Report type. Currently always `daily`. - `accountID` (string): UUID of the account the report covers. - `periodStart` (string): RFC 3339 start of the reported day (inclusive). - `periodEnd` (string): RFC 3339 end of the reported day (exclusive). - `fileName` (string): File name of the generated CSV report. - `sizeBytes` (integer): Size of the report file, in bytes. - `checksum` (string): SHA-256 hash of the report file's contents, hex-encoded. - `rowCount` (integer): Number of payment rows in the report, excluding header lines. Can be `0`. - `generatedAt` (string): RFC 3339 timestamp of when the report was generated. **reconciliation\_report.generated** ```json { "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "type": "reconciliation_report.generated", "timestamp": "2026-09-07T01:00:04.902117Z", "data": { "reportID": "8c4e2f1a-6b3d-4a9e-b7c5-2d1f0e9a8b76", "type": "daily", "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d", "periodStart": "2026-09-06T00:00:00Z", "periodEnd": "2026-09-07T00:00:00Z", "fileName": "8c4e2f1a-6b3d-4a9e-b7c5-2d1f0e9a8b76-daily.csv", "sizeBytes": 2148, "checksum": "ad9c12c8986f4d21226f07a06e406c21ccd93e7b93a2b47053f5ec28e590c7bf", "rowCount": 6, "generatedAt": "2026-09-07T01:00:03.418Z" } } ``` > **Note:** For guidance on receiving and processing these events, see [Handle Webhook Events](https://developer.lydian.com/guides/handle-webhook-events.md).