Webhooks

When a payment reaches a final status, we send a signed POST request to your server. Verify the signature, then update the order.

Where notifications go

  • The key's default webhook URL, set in the key settings.
  • Or webhook_url passed when creating a payment — it takes priority for that payment.
  • The address must be public. Internal and private addresses are rejected and not retried.

When we send

On the payment's final statuses: paid, expired, canceled, failed and manual_confirmation.

What we send

Body
{
  "event": "invoice.status_changed",
  "payment_id": "pay_3f9a1c2b7d4e5f60",
  "bill_uid": "3f9a1c2b-7d4e-5f60-…",
  "order_id": "order_123",
  "status": "paid",
  "amount": 100.0,
  "currency": "USDT",
  "customer_email": "",
  "customer_name": "",
  "timestamp": 1763380800
}

For status paid the body also carries the fee breakdown: commission, commission_rate, commission_fixed, net_amount and net_currency.

HeaderValue
X-Webhook-Signaturesha256=<hex>: the signature of the body, see below
X-Webhook-Eventacquiring.invoice_status_changed
X-Webhook-IdID of the notification. The same on every retry — use it to ignore duplicates
X-Webhook-TimestampWhen the event was created, Unix seconds. Not covered by the signature
User-AgentTeleportExchange-Webhook/1.0

Verifying the signature

  • The signature is HMAC-SHA256 of the raw request body, hex-encoded in lower case, sent as sha256=<hex>.
  • The key is your webhook secret exactly as the key settings show it — the whole string, including the whsec_ prefix.
  • Compute it over the body bytes as they arrived, before parsing the JSON: re-serialising changes the bytes and breaks the signature.
  • Compare in constant time. Reject the request if the header is missing or does not match.
  • Use timestamp inside the body, which is covered by the signature, to refuse notifications that are too old.
Python
import hashlib, hmac

def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")
Node.js
import crypto from "node:crypto"

function isValid(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(header || "")
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Which key signs

The secret of the API key the payment was created with. For payments created before signing was introduced: the key of the same account, otherwise the key with the same webhook URL, otherwise your oldest active key. If you have no active key at all, the notification is sent without a signature.

Delivery and retries

  • Reply with any 2xx within 10 seconds. Anything else counts as a failed attempt.
  • A failed delivery is retried after 30 seconds and again after 5 minutes — three attempts in total, with the same body and the same X-Webhook-Id.
  • After the third failure the notification is marked failed and not retried automatically. The payment itself is not affected: its status is always available through the API.

WooCommerce

Plugin version 1.1.0 or later is required, with the Webhook Secret filled in. Copy the secret from your key settings (it starts with whsec_). The plugin verifies every notification and rejects with 403 any that has no signature, a wrong one, or arrives while the secret field is empty. Download it — one PHP file for wp-content/plugins/: English https://gate.teleport.ltd/api/crypto-acquiring/developers/download/woocommerce/, Russian https://gate.teleport.ltd/api/crypto-acquiring/developers/download/woocommerce-ru/.

Check a payment's status at any time
curl https://gate.teleport.ltd/api/crypto-acquiring/v1/invoice/<bill_uid>/ \
  -H "X-API-Key: <YOUR_API_KEY>"

Teleport

Run your financial operations from one place.

Tell us how your business works. We'll show you the platform, map your current financial flow and discuss the right setup.