When we send a callback
We send a callback whenever a live transaction reaches one of these final states:
We do not send callbacks for in-progress states (
pending, pending_approval, processing) — poll getPayoutStatus to observe those.
Callbacks are not sent for sandbox transactions.
Registering a URL
Set your Callback URL in Developer Tools. Requirements:https://only- Must resolve to a public IP (private, loopback, link-local, and cloud-metadata addresses are rejected — at save time and again at delivery time)
The request we send
Verify the signature
Recompute the HMAC and compare in constant time. Reject anything stale or mismatched.Idempotency
Every callback carries a uniquex-pontis-event-id. We do not currently retry, but you should still:
- Store recent event IDs (e.g. last 24 hours)
- Reject duplicates silently with a
200 OK - Always respond with 2xx even on duplicates — non-2xx is logged as a delivery failure
Delivery failures
If your endpoint returns non-2xx or times out (10 s), the failure is logged on our side and the callback is not retried. Fall back to pollinggetPayoutStatus if you suspect a missed callback.
Local testing
While you’re developing, point the callback URL at a public service like webhook.site or a tunnel (cloudflared, ngrok) in front of your local server. We do not accept private IPs or localhost URLs — the address must resolve to a public endpoint over HTTPS.