Webhooks

Receive real-time notifications when deposits are completed.

Register a Webhook

Use the Telegram Bot command in the group linked to your partner account:

/registerwebhook deposit https://mysite.com/webhook/liqora my_secret_123

# Parameters:
#   deposit       — event type
#   URL           — endpoint that will receive the POST
#   secret        — key for HMAC-SHA256 verification

Note

Registering a new webhook automatically deactivates any previous webhook of the same type. The bot deletes your command message to protect the secret.

Delete Webhooks

/deletewebhooks deposit

# Deactivates all webhooks of type "deposit"

Event: deposit.completed

Fired when L-BRL is successfully sent to the partner's Liquid address (status TX_SENT).

Headers

Webhook headers

Content-TypestringRequired

application/json

X-Liqora-SignaturestringRequired

HMAC-SHA256 hex digest of the body using your secret

X-Liqora-EventstringRequired

Event type (deposit.completed)

Payload

Payload fields

eventstringRequired

"deposit.completed"

chargeIdstring (UUID)Required

PIX charge ID

settlementIdstring (UUID)Required

Settlement ID

liquidTxidstring (hex)Required

Transaction ID on the Liquid Network

amountstringRequired

Gross amount in BRL (e.g. "10.00")

feeAmountstringRequired

Liqora fee (e.g. "0.10")

netAmountstringRequired

Net amount (e.g. "9.90")

destinationAddressstringRequired

Destination Liquid address

splitAddressstring | nullRequired

Split address (null if not configured)

splitAmountstring | nullRequired

Split amount (null if not configured)

timestampstring (ISO 8601)Required

Event timestamp

Response200

{
  "event": "deposit.completed",
  "chargeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "settlementId": "f1553ee9-7d4e-4d06-8c6e-3b944e361c75",
  "liquidTxid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "amount": "10.00",
  "feeAmount": "0.10",
  "netAmount": "9.90",
  "destinationAddress": "tlq1qqwpzsxc3cuq3q7z9ywgsxe76sz...",
  "splitAddress": null,
  "splitAmount": null,
  "timestamp": "2026-02-12T08:42:30.000Z"
}

Signature Verification

Always verify the X-Liqora-Signature header to ensure the webhook was sent by Liqora. The signature is an HMAC-SHA256 of the request body using your secret.

const crypto = require("crypto");

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post("/webhook/liqora", (req, res) => {
  const signature = req.headers["x-liqora-signature"];
  const body = JSON.stringify(req.body);

  if (!verifyWebhook(body, signature, "my_secret_123")) {
    return res.status(401).send("Invalid signature");
  }

  const { event, settlementId, liquidTxid } = req.body;
  console.log(`Deposit completed: ${settlementId}`);

  res.status(200).send("OK");
});

Retries

If your endpoint returns a non-2xx status, Liqora retries with exponential backoff:

Attempt	Delay
1st	Immediate
2nd	~5 seconds
3rd	~25 seconds
4th	~2 minutes
5th	~10 minutes

Timeout

Your endpoint must respond within 10 seconds. After 5 failed attempts, the webhook is discarded.