Payment webhooks

How it works

Set a webhook URL

Set webhookUrl when you create the session. The response returns a whsec_ secret for verifying signatures.

Verify the signature

Check X-Signature-256 against the raw request body. Reject requests with a missing or invalid signature.

Fulfill once

Match the paid session to your order, verify the amount, and fulfill it only once.

Events

Event	When Locus sends it
`checkout.session.paid`	Payment confirmed on-chain
`checkout.session.expired`	Session expired without payment

Each event includes the session ID, amount, currency, payment transaction hash, payer address, payment time, and the metadata you set on the session. The event name and session ID are also sent in the X-Webhook-Event and X-Session-Id headers.

Verify the signature

verify-webhook.ts

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  const receivedBytes = Buffer.from(signature);
  const expectedBytes = Buffer.from(expected);
  return receivedBytes.length === expectedBytes.length &&
    crypto.timingSafeEqual(receivedBytes, expectedBytes);
}

Pass the raw request body as payload, the X-Signature-256 header as signature, and your whsec_ secret as secret.

Getting started

Features

Agent tools

Build with Locus

Checkout

How it works

Events

Verify the signature

Next steps

Integration example

Payment Router

​How it works

​Events

​Verify the signature

​Next steps

Integration example

Payment Router

How it works

Events

Verify the signature

Next steps