Report conversions from creator referral codes

1. 1

   Easily Promote

   A creator joins your campaign and gets a code

   Each creator gets one code, like ACME-TUNDE. You can also supply codes from your own referral system instead.

2. 2

   Creator

   The creator shares the code with their audience

   Viewers see the content and enter the code when they sign up, install, deposit or buy. They never interact with Easily Promote.

3. 3

   Your server

   Your app checks the code with us

   When a user enters a code, your server asks us whether it’s valid and accepts or rejects it. There is nothing to load or sync — a new creator’s code works the moment they join.

4. 4

   Your server

   Your server tells us about the conversion

   When your definition of a conversion happens, send one signed POST with the code, the event type and a unique event ID.

5. 5

   Easily Promote

   We credit the creator

   We verify the signature, match the code to its creator and update your campaign and the creator’s dashboard in real time.

Referral tracking runs alongside a campaign’s views. Creators can start posting before your integration is live; conversions start counting as soon as you send them.

1. In the Easily Promote app, open Referral tracking settings and generate a signing key.
2. Store the key ID and secret on your server as EP_KEY_ID and EP_WEBHOOK_SECRET. Never ship them in an app or website.
3. Add a referral code field to your sign-up (or checkout) and check each code with the validation endpoint before accepting it.
4. Send a conversion every time someone who used a valid code converts. Use "test": true while you build — nothing is counted.
5. Turn on referral tracking for a campaign. Creators’ codes start working as soon as they join.

Every request carries two headers. X-EP-Key-Id says which key signed it. X-EP-Signature proves the body came from you and hasn’t been changed or replayed.

1. Serialize the JSON body to a string. Sign and send that exact string — re-serializing after signing changes the bytes and the signature will not match.
2. Take the current Unix time in seconds as t. It must be within 5 minutes of our clock.
3. Compute HMAC-SHA256 of ${t}.${body} using your secret, as lowercase hex.
4. Send X-EP-Signature: t=<t>,v1=<hex>.

When a user enters a referral code in your sign-up, checkout or deposit flow, ask us whether it’s valid before you accept it. You never load or sync creators’ codes — a code works the moment its creator joins a campaign. The endpoint is https://api.easilypromote.com/api/webhooks/codes/validate.

POST https://api.easilypromote.com/api/webhooks/codes/validate
Content-Type: application/json
X-EP-Key-Id: key_4f9a2c81d0e3
X-EP-Signature: t=1789408800,v1=…

{ "code": "ACME-TUNDE" }

Sign it exactly like a conversion. A code check records nothing; report the conversion separately once it happens.

not_found

No creator in your account has this code.

disabled

You turned this code off.

campaign_not_accepting

The code’s campaign was cancelled or ended more than 7 days ago.

Copy your exact URLs from Referral tracking settings in the app. In production the conversion endpoint is https://api.easilypromote.com/api/webhooks/conversions.

POST https://api.easilypromote.com/api/webhooks/conversions
Content-Type: application/json
X-EP-Key-Id: key_4f9a2c81d0e3
X-EP-Signature: t=1789408800,v1=d92d1380…6016203

{
  "event_id": "signup-10482",
  "code": "ACME-TUNDE",
  "event": "signup",
  "timestamp": "2026-09-14T18:00:00Z"
}

Every response is JSON. A 200 means we have the event — including duplicates — so you can stop sending it.

Networks fail, so send events from a queue or background job rather than inside the user’s request.

• Retry timeouts, connection errors, 429 and 5xx with exponential backoff — for example after 1s, 2s, 4s, 8s — for up to 24 hours.
• Keep the same event_id on every retry. If an earlier attempt did reach us, the retry returns ignored and nothing is counted twice.
• Re-sign each attempt with a fresh t; a signature older than 5 minutes is rejected.
• Don’t retry 400, 401, 404 or 409 without changing something — the same request will fail the same way.

const crypto = require("crypto");

// Call from your sign-up handler before accepting a referral code.
async function checkReferralCode(code) {
  const body = JSON.stringify({ code });
  const t = Math.floor(Date.now() / 1000);
  const v1 = crypto
    .createHmac("sha256", process.env.EP_WEBHOOK_SECRET)
    .update(`${t}.${body}`)
    .digest("hex");

  const res = await fetch("https://api.easilypromote.com/api/webhooks/codes/validate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-EP-Key-Id": process.env.EP_KEY_ID,
      "X-EP-Signature": `t=${t},v1=${v1}`,
    },
    body,
    signal: AbortSignal.timeout(3000),
  });
  if (!res.ok) throw new Error(`Code check failed: ${res.status}`);
  const result = await res.json(); // { valid, code, reason? }
  return result.valid;
}

Store EP_KEY_ID and EP_WEBHOOK_SECRET as environment variables on your server. Both cURL examples are safe to run as-is: a code check records nothing, and the conversion example sends a test event.

• Try requests from the app

  Referral tracking settings can check a code or send a test conversion for you. We sign the request with your key and run it through the real checks, so you can see a working exchange before writing any code.

• Send test events from your server

  Add "test": true to any request. We verify the key and signature, mark you Connected and tell you whether the code would match — without recording a conversion.

• Read the request log

  Recent requests in the app lists every signed request from the last 30 days with the status we returned and the reason for any rejection.

Stuck? Email [email protected] with the event_id and the response you received.