Postback

Postbacks are server-to-server HTTP callbacks that FYNXT fires to your downstream systems the moment a referred client completes a tracked action. They are how you get registration, deposit and trade events into your CRM, ad network, analytics or data warehouse in near real-time — without polling.

What is a postback?

When you register a postback endpoint and subscribe it to one or more event types, FYNXT holds a durable queue. Every matching referral_event is serialized to JSON, signed with your endpoint's shared secret, and delivered to your URL via POST.

A postback is the inverse of a pixel: instead of the client's browser notifying a third party, the broker's server notifies the third party directly. This keeps attribution accurate when the client drops off, clears cookies, or completes the action hours later on a different device.

End-to-end flow

Visitor clicks a FYNXT link → click row written, FYNXT_SESSION_ID cookie set.
Visitor completes a tracked action on your site (e.g. registration).
Your backend calls POST /v1/referral/events or your browser calls fynxt.track().
FYNXT resolves the event to the attributed click, records the referral_event.
FYNXT looks up every postback endpoint subscribed to that event type.
For each subscriber, FYNXT queues a delivery attempt, signs the payload, and POSTs it.
Your endpoint returns a 2xx. Non-2xx responses are retried with exponential backoff.

Your endpoint

Your endpoint must:

Accept HTTPS with a valid certificate.
Handle POST with Content-Type: application/json.
Return 2xx within 10 seconds.
Be idempotent — every delivery includes an event_id; duplicates can arrive on retry.

Payload shape

Every postback carries a stable envelope around an event-specific data object:

Field	Type	Description
`id`	string	Unique delivery ID. Stable across retries.
`event_id`	string	Underlying referral event ID.
`event_type`	string	One of `REGISTRATION`, `FIRST_DEPOSIT`, etc.
`created`	int (unix)	When the event occurred.
`livemode`	boolean	`true` in production, `false` in test.
`data`	object	Event-specific body. See Event objects.

Signing and replay

Every request carries an FX-Signature header containing a timestamp and an HMAC-SHA256 of the raw body using the endpoint's shared secret. Verify it before trusting the payload. Reject requests with a timestamp older than five minutes to prevent replay.

FX-Signature: t=1745000000,v1=5257a869e7ec...3f7a9

Retries

Any non-2xx response, connection failure or timeout triggers a retry. FYNXT retries up to 12 times over 72 hours with exponential backoff (1m, 2m, 5m, 10m, 30m, 1h, 2h, 4h, 8h, 16h, 24h, 48h). After the final attempt, the delivery is moved to a dead-letter queue that you can replay from the dashboard.

Order is not guaranteed. Retries can cause later events to arrive before earlier ones. Always key off event_id and compare created timestamps when sequence matters.

Quickstart

Create an endpoint in the FYNXT dashboard. Copy the signing secret.
Subscribe it to the event types you care about.
Deploy a handler on your server that verifies the signature and writes to your store.
Trigger a test event with POST /v1/postback_endpoints/:id/test.
Go live.

See the JavaScript SDK for browser-side capture, and the REST API reference for every endpoint.

← Previous

Referral overview

JavaScript SDK