Partner Webhook

If you provide a webhook_url at onboarding, Proof POSTs a normalized transaction event to that URL on every status change. This channel is optional — many partners rely on WebSocket and polling only. The webhook is most useful when your backend needs to react server-side without keeping a persistent connection open.

Delivery model

Attribute	Value
HTTP method	`POST`
Content-Type	`application/json`
Trigger	Every status change for any of your transactions
Delivery	Best-effort, fire-and-forget
Retries	None on a single status change. Proof relies on internal retries to redeliver, which can result in the same `merchant_transaction_id` arriving multiple times
Authoritative source	No — pair the webhook with polling or WebSocket for state your business depends on

Payload

{
  "merchant_transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "buy",
  "status": "completed",
  "currency": "USDT",
  "network": "TRC20",
  "crypto_amount": "99.50",
  "fiat_currency": "EUR",
  "fiat_amount": "100.00",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-01T10:03:45Z"
}

Field	Type	Notes
`merchant_transaction_id`	string	Stable across retries; use as your idempotency key
`type`	string	`"buy"` or `"sell"`
`status`	string	Normalized: `pending`, `processing`, `completed`, `failed`, `cancelled`
`currency`	string	Crypto currency
`network`	string	Blockchain network
`crypto_amount`	string	May be empty before `processing`
`fiat_currency`	string	Fiat currency
`fiat_amount`	string	Fiat amount
`created_at`	string	ISO 8601 timestamp (UTC)
`updated_at`	string	ISO 8601 timestamp (UTC) of this status change

The status enum matches GET /widget/transactions/{id} and the WebSocket tx.update event.

Handler expectations

Respond with any 2xx status code as quickly as possible. Heavy work should happen asynchronously after acknowledgement.

Be idempotent on merchant_transaction_id + status. Treat duplicate deliveries as no-ops.

Treat the webhook as advisory. If the webhook stops arriving for a transaction you care about, fall back to polling or WebSocket — do not block business logic on the webhook alone.

Example handler (Express)

app.post("/proof-webhook", express.json(), async (req, res) => {
  const event = req.body;

  // ACK first
  res.sendStatus(200);

  // Process asynchronously, idempotently
  await reconcileTransaction(event.merchant_transaction_id, event.status, event);
});

Updating the webhook URL

Contact the Proof team to add, change, or remove your webhook_url. There is no self-service endpoint.

Getting started

Guides

API Reference

Delivery model

Payload

Handler expectations

Example handler (Express)

Updating the webhook URL

​Delivery model

​Payload

​Handler expectations

​Example handler (Express)

​Updating the webhook URL

Delivery model

Payload

Handler expectations

Example handler (Express)

Updating the webhook URL