Webhooks

Webhooks are automated messages sent from Lydian to another application when a specific event occurs, enabling real-time data sharing between systems by delivering an HTTP POST payload to a configured URL. In this guide, we'll look at how the webhooks can be set up.

Set Up Webhooks

To set up a webhook in Lydian, navigate to the Lydian Merchant Portal and go to Developer » Webhooks. Click the Create Webhook button to register a new webhook listener, specifying a name and the target URL where you want to receive event notifications. Whenever an event occurs, Lydian will send a POST request to your specified URL with the payload structured with the following properties in the JSON format.

Webhooks Payload

Name
accountID
Type
string
Description
Account ID for the transaction.
Name
lydianpayTransactionID
Type
string
Description
Unique identifier for the transaction.
Name
merchantTransactionID
Type
string
Description
External unique identifier attached by the merchant for the transaction.
Name
status
Type
integer
Description
Status of the transaction. Status as 0 means the transaction is pending, 1 means the transaction is success.
Name
timestamp
Type
string
Description
Timestamp of the event.
Name
error
Type
string
Description
Error message if there are any.
Name
merchantID
Type
string
Description
Merchant ID for the transaction.

example payload

{
    "accountID": "926751ea-8255-438c-a3a2-8e895092e38a",
    "lydianpayTransactionID": "12a3e743-c1a4-478f-8fcb-722c1d35b98a",
    "merchantTransactionID": "sample ID",
    "status": 1,
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "merchantID": "d51a0d59-d1b0-4b50-8e95-58b1857581db"
}

Create Webhook

POST /accounts/{accountUUID}/webhooks

POST

/accounts/{accountUUID}/webhooks

curl --location '{API_BASE_URL}/accounts/{AccountUUID}/webhooks' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{WEBHOOK_NAME}",
    "url": "{WEBHOOK_URL}"
}'

Create Webhook Response

Name
uuid
Type
string
Description
Unique identifier for the webhook.
Name
signingKey
Type
string
Description
Signing key used to verify webhook payloads.

example response

{
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "signingKey": "whsec_abc123def456"
}

List Webhooks

GET /accounts/{accountUUID}/webhooks

GET

/accounts/{accountUUID}/webhooks

curl --location '{API_BASE_URL}/accounts/{AccountUUID}/webhooks' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

List Webhooks Response

Name
webhooks
Type
array
Description
List of webhooks associated with this account.
Webhook Object
Name
uuid
Type
string
Description
Unique identifier for the webhook.
Name
name
Type
string
Description
Name of the webhook.
Name
url
Type
string
Description
URL that receives webhook events.
Name
enabled
Type
boolean
Description
Whether the webhook is currently enabled.

example response

{
    "webhooks": [
        {
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "Order Notifications",
            "url": "https://example.com/webhooks/lydian",
            "enabled": true
        }
    ]
}

Update Webhook

PUT /accounts/{accountUUID}/webhooks/{webhookUUID}

PUT

/accounts/{accountUUID}/webhooks/{webhookUUID}

curl --location --request PUT '{API_BASE_URL}/accounts/{AccountUUID}/webhooks/{webhookUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{WEBHOOK_NAME}", // OPTIONAL
    "url": "{WEBHOOK_URL}", // OPTIONAL
    "enabled": {ENABLED} // OPTIONAL
}'

Returns 204 No Content on success.

Delete Webhook

DELETE /accounts/{accountUUID}/webhooks/{webhookUUID}

DELETE

/accounts/{accountUUID}/webhooks/{webhookUUID}

curl --location --request DELETE '{API_BASE_URL}/accounts/{AccountUUID}/webhooks/{webhookUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

Returns 204 No Content on success.