Webhooks API

123hub sends outgoing webhooks to merchant callback URLs when payment or payout events occur. Merchants can configure callbacks through onboarding/dashboard flows, Backoffice operations, or per-payment webhook_url.

Event Types

Event	Description
`payment.created`	Deposit or withdrawal payment was created
`payment.completed`	Deposit or withdrawal payment completed successfully
`payment.failed`	Deposit or withdrawal payment failed
`payment.cancelled`	Payment was cancelled
`payment.refunded`	Payment was refunded

Withdrawals use the same payment.* callbacks as deposits and are identified by data.result.payment.destination: "out". payment.processing is a payment status value, not a currently emitted merchant callback event. Some account tooling may also expose balance.updated, merchant.updated, and webhook.test events outside the payment lifecycle. Opt-in public support selectors are ticket.created, ticket.updated, ticket.status_changed, ticket.comment.created, ticket.reopened, refund.requested, refund.status_changed, and chargeback.created. They use the same delivery headers/retries but a minimal public-resource payload; see Support webhooks. Existing subscriptions are not expanded automatically.

Delivery Payload

Outgoing payment webhook deliveries use this envelope:

{
  "id": "pay_123:payment.completed",
  "created_at": "2026-04-02T08:23:04.379Z",
  "data": {
    "next": null,
    "result": {
      "payment": {
        "amount": { "value": 500000, "currency": "ARS" },
        "identifiers": {
          "c_id": "merchant-order-1",
          "h_id": "pay_123",
          "p_id": "provider-ref-123"
        },
        "status": {
          "status": "success",
          "final": true,
          "success": true,
          "error": null
        },
        "timestamps": {
          "created": "2026-04-02T08:22:21.453Z",
          "updated": "2026-04-02T08:22:22.795Z",
          "finished": "2026-04-02T08:22:21.790Z"
        },
        "destination": "in",
        "receiver": {},
        "operations": []
      }
    },
    "success": true,
    "request_id": "729aebbf-5a6b-4299-87fa-1cf05c1121a6",
    "processing_time": 0
  },
  "merchant_id": "19"
}

Internal indexing fields are stripped before delivery. Do not depend on fields prefixed with _.

Delivery Headers

Header	Description
`Content-Type`	`application/json`
`X-Data-Hash`	SHA-512 signature: `SHA512(rawBody + webhook secret)`
`X-Webhook-Id`	Delivery/event identifier
`X-Webhook-Timestamp`	ISO 8601 delivery timestamp
`X-Webhook-Nonce`	Per-delivery nonce
`X-Webhook-Signature-V2`	Compatibility signature: `SHA512(timestamp + rawBody + webhook secret)`
`X-Webhook-Signature-V3`	Preferred signature: `HMAC-SHA512(timestamp.nonce.webhookId.rawBody, secret)`

Use X-Webhook-Signature-V3 when present. It binds replay metadata and the raw body. Use X-Webhook-Signature-V2 or X-Data-Hash only for backward-compatible verification. Webhook create/rotation reveals a dedicated webhook-only secret once. Historical API-compatible rows do not deliver until the webhook secret is explicitly rotated; API-key rotation is independent. For a callback auto-created by params.payment.webhook_url, derive the webhook secret as lowercase HMAC-SHA256(apiSecret, "quadpay:merchant-webhook-signing:v1"), using the exact test or production API secret that authenticated that payment create. The URL is bound to that payment and never receives another payment’s events.

Signature Verification

Verify against the exact raw request body bytes. Do not parse and re-serialize JSON before hashing.

Node.js

const crypto = require("crypto");

function safeCompareHex(expected, received) {
  if (!/^[a-f0-9]{128}$/i.test(received || "")) {
    return false;
  }
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex"),
  );
}

function verifyWebhook(rawBody, webhookSecret, receivedHash) {
  const expected = crypto
    .createHash("sha512")
    .update(Buffer.concat([Buffer.from(rawBody), Buffer.from(webhookSecret)]))
    .digest("hex");

  return safeCompareHex(expected, receivedHash);
}

function verifyWebhookV2(rawBody, webhookSecret, timestamp, receivedHash) {
  const timestampMs = Date.parse(timestamp || "");
  if (
    !Number.isFinite(timestampMs) ||
    Math.abs(Date.now() - timestampMs) > 5 * 60 * 1000
  ) {
    return false;
  }

  const expected = crypto
    .createHash("sha512")
    .update(String(timestamp) + rawBody.toString("utf8") + webhookSecret)
    .digest("hex");

  return safeCompareHex(expected, receivedHash);
}

function verifyWebhookV3(
  rawBody,
  webhookSecret,
  timestamp,
  nonce,
  webhookId,
  receivedHash,
) {
  const timestampMs = Date.parse(timestamp || "");
  if (!timestamp || !nonce || !webhookId || !Number.isFinite(timestampMs)) {
    return false;
  }
  if (Math.abs(Date.now() - timestampMs) > 5 * 60 * 1000) {
    return false;
  }

  const expected = crypto
    .createHmac("sha512", webhookSecret)
    .update(
      [timestamp, nonce, webhookId, Buffer.from(rawBody).toString("utf8")].join(
        ".",
      ),
    )
    .digest("hex");

  return safeCompareHex(expected, receivedHash);
}

After verification, read payment data from payload.data.result.payment.

Retry Policy

Webhook delivery succeeds on any HTTP 2xx response. Non-2xx responses, timeouts, network errors, oversized payloads, URL validation failures, or an open circuit breaker are treated as failures. Default webhook retry settings:

Setting	Default	Notes
`timeout_seconds`	`30`	Configurable from 5 to 60 seconds
`max_retries`	`3`	Configurable from 1 to 10 attempts
`retry_delay_seconds`	`1`	Base delay used by exponential backoff

The retry delay uses exponential backoff with jitter:

delay = min(max(random(0, 2^(attempt - 1) * retry_delay_seconds), 1s), 24h)

Retries are processed by a scheduler. Delivery order is not guaranteed, so handlers must be idempotent.

Idempotency

Use id plus data.result.payment.status.status as a practical deduplication key. data.request_id is unique per generated callback body and should not be used as the business idempotency key.

Webhook Management

Legacy callback configuration routes under /api/v1/webhooks are no longer part of the public API. Configure merchant callback URLs through onboarding or Backoffice operations. Payment-level re-delivery remains available through the signed endpoint below.

Merchant Payment Webhook Resend

For payment-level re-delivery, merchants can also use the signed API endpoint:

POST /api/v1/payments/{paymentId}/webhook/resend

This mutation requires X-Data-Application-Id, X-Data-Hash and the webhooks.update scope. X-Data-Timestamp plus X-Data-Nonce are an optional pair; a partial pair is rejected. It is throttled to 10 requests per minute. The JSON body is:

{
  "payment_id": "pay_01HX...",
  "operation_id": "merchant-resend-1001"
}

payment_id must equal the path parameter. Reuse operation_id only for an exact retry of the same resend intent. Without replay headers, X-Data-Hash remains SHA512(raw JSON body + API secret). With both optional replay headers, the signature payload is the exact UTF-8 concatenation below, followed by the raw JSON body; X-Data-Hash is SHA512(payload + API secret):

quadpay-merchant-webhook-resend-v1
POST
/api/v1/payments/{paymentId}/webhook/resend
{unixTimestamp}
{nonce}

{rawJsonBody}

Per-Payment Webhook URL

payment.in and payment.out accept params.payment.webhook_url. In production, use an absolute public HTTPS URL including the protocol. The system validates it at request time and again before delivery to reduce SSRF risk. The first use of a new URL creates a webhook-only derived secret. Compute the same lowercase hex value with HMAC-SHA256(exactAuthenticatedApiSecret, "quadpay:merchant-webhook-signing:v1") and use that derived value for callback verification.

Getting Started

Guides

SDKs & Examples

Reference

Webhooks API

Webhooks API

Event Types

Delivery Payload

Delivery Headers

Signature Verification

Retry Policy

Idempotency

Webhook Management

Merchant Payment Webhook Resend

Per-Payment Webhook URL

​Webhooks API

​Event Types

​Delivery Payload

​Delivery Headers

​Signature Verification

​Retry Policy

​Idempotency

​Webhook Management

​Merchant Payment Webhook Resend

​Per-Payment Webhook URL

Webhooks API

Event Types

Delivery Payload

Delivery Headers

Signature Verification

Retry Policy

Idempotency

Webhook Management

Merchant Payment Webhook Resend

Per-Payment Webhook URL