Integrations & postbacks
The Integrations section gives you the connection details needed to report web or store conversions to Attribloom.
Key values
Postback URL. The endpoint your server calls when a sale completes. POST each conversion here, signed with your Postback secret.
Redirect base. The root URL of every tracking link. A complete tracking link is the Redirect base plus the affiliate's unique code. When a visitor opens the link, Attribloom records the click and immediately forwards them to the campaign's destination.
Postback secret. A secret key used to sign postback requests via HMAC. Keep this server-side only. Never expose it in client code, browser URLs, or public repositories. Anyone who holds the secret can forge a conversion.
How postbacks work
When a sale completes on your server:
1. Build the postback payload (conversion amount, currency, a unique order reference, and the affiliate's code or click ID).
2. Sign the payload with the Postback secret using HMAC.
3. POST the signed request to your Postback URL.
4. Attribloom verifies the signature, matches the conversion to the affiliate's recorded click, and credits commission.
Sign the exact raw JSON bytes as `sha256=` plus the lowercase hex HMAC-SHA256 of `timestamp + "." + rawBody`. Send the surface id, unix-seconds timestamp, and signature in `x-ea-surface`, `x-ea-timestamp`, and `x-ea-signature`. The timestamp may differ from Attribloom's clock by at most 300 seconds.
An invalid signature returns `401`. A valid conversion whose click or referral cannot be matched is accepted as `200` with status `unattributed` and credits no commission. Replaying the same `externalId` is safe and returns status `duplicate` without a second accrual.
Refund a conversion
POST a signed request to `/v1/conversions/refund`, not `/v1/refund`. Use the original conversion's `externalId`, a stable `refundId`, integer `refundedMinor`, and the original three-letter currency. A partial refund sends only that event's partial amount. Replaying the same `refundId` is idempotent.
Use `eventType: refund` for a refund. If the platform later reverses that refund, send the required `refundId` with `eventType: refund_reversed`. Replaying the reversal is safe because Attribloom only reverses a conversion still marked refunded. The endpoint returns `404` when the original conversion is absent and `409` when currencies differ.
The public machine contract is available at `https://api.attribloom.com/openapi.json`.
When is the secret created?
The Postback secret is created when you provision your first campaign. If you have not yet created a campaign, the Integrations section will prompt you to do so.