Skip to main content

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.
Sign over the raw bytes you received, not a re-serialized JSON object. Re-serializing changes whitespace/ordering and the signature won’t match.

Idempotency

Every callback carries a unique x-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 polling getPayoutStatus 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.