Referral Created Webhook | FirstPromoter v2

Assuming someone signs up through a promoter/affiliate's link and you want to reward the referred person "75 credits" right away, just for joining. In this example, 75 credits are supposed to be given the moment they sign up, even before they pay/purchase your product or service.

The notification to listen for

FirstPromoter sends a referral.created event/notification, the instant someone new is tracked as a referral. It tells you who just signed up.

Example Payload

{
    "event_id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
    "event_type": "referral.created",
    "action": "created",
    "entity_type": "referral",
    "entity_id": null,
    "changes": {},
    "data": {
        "id": 10000001,
        "email": "[email protected]",
        "uid": "",
        "state": "signup",
        "entry_source": "cookie",
        "username": null,
        "visitor_sub_id": null,
        "split_details": null,
        "first_name": null,
        "last_name": null,
        "website": null,
        "comment": null,
        "traffic_source": null,
        "created_at": "2026-01-15T10:30:00Z",
        "customer_since": null,
        "promoter_campaign": {
            "id": 20000001,
            "campaign_id": 30000001,
            "promoter_id": 40000001,
            "created_at": "2026-01-01T09:00:00Z",
            "promoter": {
                "id": 40000001,
                "email": "[email protected]",
                "name": "Alex Promoter"
            },
            "campaign": {
                "id": 30000001,
                "name": "Referral Program",
                "color": "#4F46E5",
                "language": null
            }
        },
        "fraud_check": "no_suspicion",
        "is_expired": false,
        "created_by_user_email": null,
        "custom_status": null,
        "metadata": {}
    },
    "timestamp": "2026-01-15T10:30:00Z"
}

The part worth knowing upfront

The referral.created does not include a reward amount. This means that when a person (a lead/referral) signs up, there's no sale data for FirstPromoter to perform any reward calculation; therefore, it has nothing to hand you. The "75 credits" isn't a value you read off the notification. It's a number you decide on your side, matching whatever you've promised in your program, and apply yourself every time this notification arrives.

Putting it together

Subscribe your webhook endpoint to referral.created.
Pick a fixed reward amount in your own system (e.g. a constant like REFERRAL_SIGNUP_REWARD = 75).
Every time a referral.created notification arrives:
1. Confirm if the data.entry_source is "cookie" ( the "cookie" value indicates the referral link was used).
2. Take the referred person's email from the payload.
3. Credit their account with your fixed amount.
4. Acknowledge receipt by returning status code 200, so FirstPromoter doesn't retry the delivery.

That's the entire flow; there's no approval step to wait for here, since this reward isn't tied to a commission at all. It's triggered purely by the signup itself.

Worth testing before you build

Use the Run Test feature in FirstPromoter to send test data or perform a sign-up test using one of the promoter's referral links, and inspect the actual payload that arrives.

For testing purposes, you can use https://webhook.site to receive a webhook event and confirm the field you're reading the email from matches what's really there before wiring up the reward logic.