WebHooks

When an invoice reaches a terminal state, we send one POST to its callback_url. This webhook is the source of truth for fulfillment — act on it, not on the customer returning to your success_url.

What you need to do

Expose an HTTPS endpoint

Set it as callback_url on the invoice, or as your business default. It must accept POST with a JSON body.

Verify the signature

Confirm the request is from us before trusting it (see Verifying).

Respond 2xx quickly

Any 2xx marks the delivery as received. Do heavy work asynchronously — acknowledge first, process after.

Process idempotently

The same event may arrive more than once. Deduplicate on X-Webhook-Id (or invoice_uuid), and treat a repeat as a no-op.

Events

One terminal webhook per invoice.

Event	Meaning
`invoice.paid`	The invoice was paid and credited.
`invoice.canceled`	The invoice ended without payment (`expired`, `canceled`, or `fail`).

Payload

invoice.paid:

{
  "event": "invoice.paid",
  "data": {
    "invoice_uuid": "9f2c1e5a-...",
    "external_id": "order-4821",
    "status": "success",
    "currency": "UAH",
    "amount": "1000.00",
    "paid_amount": "1050.00",
    "credited_usdt": "24.80",
    "adjusted": false
  }
}

invoice.canceled:

{
  "event": "invoice.canceled",
  "data": {
    "invoice_uuid": "9f2c1e5a-...",
    "external_id": "order-4821",
    "status": "expired",
    "currency": "UAH",
    "amount": "1000.00",
    "adjusted": false
  }
}

Field	Description
`invoice_uuid`	Our invoice id.
`external_id`	Your order id.
`status`	`success` for paid; `expired`, `canceled`, or `fail` for canceled.
`currency`	Fiat currency of the invoice.
`amount`	The order amount — reconcile against this. When `adjusted` is `true`, it is the recomputed order amount.
`paid_amount`	What the customer transferred to the card: the order plus their commission. Informational. `invoice.paid` only.
`credited_usdt`	USDT credited to your balance. `invoice.paid` only.
`adjusted`	Whether the amount was corrected after a dispute.
`original_amount`	The amount the invoice was created for. Present only when `adjusted` is `true`.

Reconcile the order against amount, and credit your customer against credited_usdt. paid_amount differs from amount whenever the customer pays the commission — it is not the order value, so do not reconcile with it.

Adjustments

If the customer transfers a different amount than the invoice asked for, we resolve it as a dispute and close the invoice at the amount that actually arrived. The webhook then carries adjusted: true and three amounts:

{
  "event": "invoice.paid",
  "data": {
    "invoice_uuid": "9f2c1e5a-...",
    "external_id": "order-4821",
    "status": "success",
    "currency": "UAH",
    "amount": "857.14",
    "original_amount": "1000.00",
    "paid_amount": "900.00",
    "credited_usdt": "21.26",
    "adjusted": true
  }
}

Here you ordered 1000, the customer owed 1050 and sent 900. Of that 900, the commission takes 42.86, so the order closed at 857.14 — and that is what was credited.

Always check adjusted. When it is true, amount is smaller (or larger) than what you ordered, so a strict equality check against your own record will reject a legitimate webhook. Fulfill against credited_usdt, and decide what to do with the difference: deliver partially, credit the actual amount, or contact the customer. A paid invoice does not guarantee full payment.

Headers

Every delivery carries:

Header	Purpose
`X-Webhook-Id`	Unique delivery id. Use it to deduplicate.
`X-Webhook-Event`	The event name, e.g. `invoice.paid`.
`X-Webhook-Timestamp`	Signing timestamp. Reject if too old (anti-replay).
`X-Webhook-Signature`	`sha256=<hmac>` — verify this.

Verifying the signature

The signature is HMAC-SHA256 over the string {timestamp}.{raw_body}, keyed with your webhook secret (from the dashboard). Compute it over the raw request body and compare against X-Webhook-Signature with a constant-time check.

import hashlib
import hmac

def verify(secret: str, headers, raw_body: bytes) -> bool:
    ts = headers["X-Webhook-Timestamp"]
    sig = headers["X-Webhook-Signature"].removeprefix("sha256=")
    expected = hmac.new(
        secret.encode(), f"{ts}.{raw_body.decode()}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

const crypto = require("crypto");

function verify(secret, headers, rawBody) {
  const ts = headers["x-webhook-timestamp"];
  const sig = headers["x-webhook-signature"].replace(/^sha256=/, "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Reject the request if the signature doesn’t match, or if X-Webhook-Timestamp is older than a few minutes. The timestamp is inside the signed string, so an attacker can’t replay an old body with a fresh timestamp.

Retries

A delivery succeeds on any 2xx. Anything else — a non-2xx status, a timeout (15s), or a connection error — is retried on a backoff schedule. By default there are 7 attempts: the first immediately, then after 1, 5, 30, 120, 360, and 720 minutes. The last attempt lands roughly 20.6 hours after the event. If all attempts fail, the delivery is marked failed — resend it manually once your endpoint is healthy.

Manual resend

POST /external/invoices/{ident}/resend-webhook Sends the latest delivery for the invoice now — expedites it if still queued, or starts a fresh attempt if it already failed or delivered. {ident} is the order_id or your external_id.

curl -X POST \
  https://api.manexx.com/api/v1/external/invoices/order-4821/resend-webhook \
  -H "X-Api-Key: $MANEXX_KEY"

Code	HTTP	When
`MERCHANT_INVOICE_NOT_FOUND`	`404`	No invoice for the given `ident`
`WEBHOOK_NOT_FOUND`	`404`	The invoice has no webhook delivery yet
`WEBHOOK_NOT_RESENDABLE`	`409`	A delivery is being sent right now
`WEBHOOK_RESEND_TOO_SOON`	`429`	Throttled; retry after `details.retry_after_seconds`

Delivery history

GET /external/invoices/{ident}/webhooks Returns the invoice’s deliveries, each with its full attempt history — useful to debug failures (status codes, errors, timings).

curl https://api.manexx.com/api/v1/external/invoices/order-4821/webhooks \
  -H "X-Api-Key: $MANEXX_KEY"

Each delivery includes: Delivery id (matches X-Webhook-Id). invoice.paid or invoice.canceled. pending, delivering, delivered, or failed. Attempts made so far, out of max_attempts. HTTP status of the most recent attempt. When the next retry is scheduled (if any). When a 2xx was received. Per-attempt log: status_code, success, error, duration_ms, triggered_by, created_at.

Getting Started

API Reference

What you need to do

Events

Payload

Adjustments

Headers

Verifying the signature

Retries

Manual resend

Delivery history

​What you need to do

​Events

​Payload

​Adjustments

​Headers

​Verifying the signature

​Retries

​Manual resend

​Delivery history

What you need to do

Events

Payload

Adjustments

Headers

Verifying the signature

Retries

Manual resend

Delivery history