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 a subscribed event occurs, Lydian sends an HTTP POST request to your URL with a Content-Type: application/json body.

For the shape of the payloads Lydian delivers and how to verify their signatures, see Webhook Events.

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}",
    "events": ["transaction.success"]
}'

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 (see Verifying Signatures). Store this securely — it is only returned in full when the webhook is created.
Name
name
Type
string
Description
Name of the webhook.
Name
url
Type
string
Description
URL that receives webhook events.
Name
status
Type
integer
Description
Status of the webhook. 1 means enabled and -1 means disabled.
Name
createdAt
Type
string
Description
RFC 3339 timestamp of when the webhook was created.

example response

{
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "signingKey": "wk_9c1d8f7e6b5a4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d",
    "name": "Order Notifications",
    "url": "https://example.com/webhooks/lydian",
    "status": 1,
    "createdAt": "2025-08-12T03:20:02.769Z"
}

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
status
Type
integer
Description
Status of the webhook. 1 means enabled and -1 means disabled.
Name
events
Type
array
Description
Event types this webhook is subscribed to (e.g. ["transaction.success"]).
Name
signingKey
Type
string
Description
Signing key used to verify payloads delivered to this webhook.
Name
accountID
Type
string
Description
UUID of the account the webhook belongs to.
Name
createdAt
Type
string
Description
RFC 3339 timestamp of when the webhook was created.

example response

{
    "webhooks": [
        {
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "Order Notifications",
            "url": "https://example.com/webhooks/lydian",
            "status": 1,
            "events": ["transaction.success"],
            "signingKey": "wk_9c1d8f7e6b5a4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d",
            "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
            "createdAt": "2025-08-12T03:20:02.769Z"
        }
    ]
}

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
    "status": {STATUS}, // OPTIONAL — 1 to enable, -1 to disable
    "events": ["transaction.success"] // 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.