Set Up Webhooks

Webhooks let Lydian notify your systems in real time when something happens — most importantly, when a payment succeeds or fails — so you don't have to poll. A webhook is an HTTPS endpoint on your side that Lydian delivers event notifications to.

Why use webhooks

During checkout you can confirm a payment by polling Get Session or Get Transaction. Webhooks are the push alternative: register an endpoint once, and Lydian sends a POST request whenever a subscribed event occurs — ideal for updating orders or triggering fulfillment without polling.

1. Create a webhook

Create a webhook in the Merchant Portal under Developer » Webhooks — provide a name and the target URL that should receive events — or via the API with your API Key.

curl --location '{API_BASE_URL}/accounts/{ACCOUNT_UUID}/webhooks' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{WEBHOOK_NAME}",
    "url": "{WEBHOOK_URL}",
    "events": ["transaction.success"]
}'

See Create Webhook for the full request and response.

2. Choose your endpoint URL

The url is where Lydian delivers events. It should be a publicly reachable HTTPS endpoint that accepts a POST with a JSON body (Content-Type: application/json) and returns quickly.

3. Select event types

Use the events array to subscribe only to the event types you care about (for example transaction.success). A webhook receives only the events it subscribed to. See Event Payloads for the available event types.

4. How this fits payment confirmation

Once configured, a completed payment triggers an event (such as transaction.success) delivered to your endpoint — a push alternative to the polling shown in Accept Your First Payment. Learn how to consume delivered events in Handle Webhook Events.

Manage webhooks

List, update, and delete webhooks via the Webhooks API reference.