Affiliate postbacks

Postbacks send your referral and commission updates to your server. Each affiliate manages their own endpoints. An endpoint is the HTTPS address that receives the updates.

Turn on postbacks

The program owner opens Settings → Program settings and chooses Enable affiliate postbacks. Affiliates can then expand Promote and open Postbacks in their portal.

Add your endpoint

1. Sign in to your affiliate portal and open Postbacks.
2. Choose Add postback.
3. Enter a name and your server’s HTTPS URL.
4. Pick the events you want. Leave Enable postback checked.
5. Choose Save postback.
6. Choose Test URL, then Refresh logs to read the result.

Use a public HTTPS URL on port 443. Local and private addresses are blocked. You can save up to 20 endpoints.

Events and payloads

There are six events: referral.created, referral.updated, referral.deleted, commission.created, commission.updated, and commission.deleted.

Each POST has data, type, and timestamp. Referral events also have params. These include the saved link’s referral code and URL query values, such as utm_source, when the program lets you see links. If a query name appears twice, its last value is used. The saved referral code takes priority over a query value with the same name.

{
  "data": {
    "id": "referral-id",
    "program_id": "program-id",
    "partner_id": "creator-id",
    "status": "lead"
  },
  "type": "referral.created",
  "timestamp": "2026-09-11T12:00:00.000Z",
  "params": { "ref": "jamie" }
}

Referral data includes its status and saved dates. A name is included only when the program allows names. Email addresses and payment provider IDs are not sent.

For commissions, status is the same as approval: pending, approved, or rejected. The separate settlement field tracks payment.

Commission data includes the amount, currency, reversed amount, approval, settlement, payout ID, customer ID, transaction ID, and saved dates when present. Customer and transaction IDs refer to records in Referral Bear. Amounts use the currency’s smallest unit, such as cents for USD. Fields with no saved value may be absent.

The postback-id header stays the same across retries. Store this ID so a retry does not run the same task twice. Events may arrive out of order. These postbacks do not have the signing key used by owner webhooks. Use a hard-to-guess endpoint URL and keep it private. Test URL sends an example record with test: true.

Read the result

Choose Refresh logs, then View payload and response. Each attempt shows the HTTP status and up to 4 KB of response text. Longer responses are marked as cut short. Use Load older deliveries to read more history.

Return a 2xx response within 15 seconds. A failed delivery is tried again after one minute, then five minutes, then another five minutes. There are four tries in total. The schedule may add a short delay. Redirects count as failures.

Choose Edit postback to change its URL or events, or turn it off. Choose Delete postback to remove it. Saved logs remain. Changing or deleting an endpoint stops its queued deliveries. Turning off the program’s postbacks or suspending an affiliate also stops delivery. A request already sent cannot be recalled.

If the program hides names or links later, those values are hidden in saved payloads. Saved responses that may contain them are also hidden. Queued payloads with those values are canceled.