Binding webhooks

We send a signed POST request on every binding status change. Charges are orders: their results come in the usual order webhooks with X-Type: ORDER_UPDATE.

Where notifications are sent

The address is resolved in this order:

1. callbackUrl of the binding (passed to POST /v1/recurring/bindings);
2. callbackUrl of the first payment order (for a binding saved with a payment);
3. callbackUrl from your merchant settings;
4. if none is set, no notifications are sent for the binding.

When notifications are sent

A notification is generated when the binding status changes: ACTIVE after the payer confirms it, FAILED, SUSPENDED, DELETED. The initial PENDING status is not sent: it is returned when the binding is created.

For a binding saved with the first payment, the ACTIVE notification usually arrives right before the order notification with the COMPLETED status.

Duplicate records are excluded by the combination of address, binding ID and status among unsent notifications.

Notification format

POST {callbackUrl}
Content-Type: application/json
X-Type: RECURRING_BINDING_UPDATE
X-Signature: HMAC-SHA512(request body, API token) in hex

Body

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "ACTIVE",
  "isTest": false,
  "externalId": "sub-42",
  "externalUserId": "user_987",
  "merchantId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e",
  "purpose": "Monthly subscription",
  "initialOrderId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c",
  "bankName": "Sberbank",
  "bankLogoUrl": null,
  "createdAt": "2026-10-21T12:34:56.000Z",
  "updatedAt": "2026-10-21T12:36:10.512Z",
  "activatedAt": "2026-10-21T12:36:10.512Z",
  "closedAt": null
}

Verify the signature

Every notification carries the X-Signature header: an HMAC-SHA512 hash of the raw request body in hex, computed with your API token as the secret. The same scheme is used for payment, payout and refund webhooks.

import crypto from "crypto";

// Your API token is the HMAC secret
const apiToken = process.env.API_TOKEN;

app.post("/webhooks/payments", (req, res) => {
  const signature = req.headers["x-signature"];
  const body = JSON.stringify(req.body);

  // Calculate HMAC-SHA512 of the raw request body and compare in hex
  const expected = crypto.createHmac("sha512", apiToken).update(body).digest("hex");

  if (expected !== signature) {
    return res.status(403).send("Invalid signature");
  }

  // Signature is valid — process the notification idempotently
  const data = req.body;
  if (data.status === "COMPLETED") {
    console.log(`Order ${data.externalId} has been paid`);
  }

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

If one endpoint receives several kinds of notifications, distinguish them by the X-Type header: ORDER_UPDATE, PAYOUT_UPDATE, REFUND_UPDATE or RECURRING_BINDING_UPDATE.

Retry policy

A circuit breaker is also applied: an address that consistently fails is temporarily excluded from delivery.

See also