What are webhooks, really?
Think of a webhook as a notification system between FirstPromoter and your website or app. Every time something meaningful happens in your affiliate program a new promoter joins, a referral signs up, a commission gets approved. FirstPromoter can send a message straight to your server the instant it happens.
What can you actually do with webhooks?
Webhooks are the bridge between "FirstPromoter knows something happened" and "your business does something about it."
A few real examples:
Give a customer a free month automatically the day their referral converts to a customer
Reward a promoter at the same time, with credits, points, or anything else
Automatically unlock a badge, perk, or higher tier inside your own product the moment a promoter crosses a revenue milestone
Get notified the instant a payout fails, so you can fix a promoter's payment details before they have to ask you what happened to their money
Send commission and payout data straight into your accounting software, so your bookkeeping doesn't depend on someone exporting a spreadsheet every month
In short: webhooks let your product feel like it knows about your affiliate program, instead of the affiliate program living in a separate tab you have to check.
Setting one up
Go to Settings → Integrations → Webhooks and click Add new webhook.
You'll fill in a few things:
The web address (URL) where you want notifications delivered. This has to be a real, secure (https://) address that your site or app is listening on.
Which events you care about. You don't have to subscribe to everything; pick only what's relevant (more on the full list below).
Which campaigns it applies to. By default, a subscription listens to all your campaigns, but you can narrow it down to just one or two if, say, you only want notifications from a specific affiliate program.
Custom headers, if your endpoint needs something like an API key to accept the request. Think of this as a way to hand over a "password" alongside every notification so your server knows it's truly from FirstPromoter.
How it works, step by step
Something happens in your account - say, a referral signs up.
FirstPromoter checks: "Does anyone have a subscription listening for this?"
If yes, it sends that subscription a notification (a small package of data) to the web address you gave it.
Your server is expected to respond with status code 200. As long as it replies with success, FirstPromoter considers the notification delivered.
If your server doesn't respond properly (it's down, it errors out, or it's just slow), FirstPromoter will automatically try again later; you don't need to do anything for that to happen.
All the events you can subscribe to
Event names follow this pattern: "entity.action". For example, referral.created means "a new referral was created". Once you know the pattern, the whole list reads itself.
They're grouped into a few categories: Promoters, Promoter campaigns, Referrals, Commissions, Payouts, Payout methods, Payment batches, and Contract documents.
For the complete, always-up-to-date list, see the Event Types reference.
What's inside a notification
Every notification FirstPromoter sends is a small package of information (technically, JSON just a structured way of writing data). You don't need to be a developer to understand the shape of it:
A unique ID for that specific event - handy so your system can tell "have I already seen this one?" and avoid acting on it twice.
The event name, like
referral.created- tells you what happened.
The action - whether something was created, updated, or deleted.
What kind of thing changed - a promoter, a referral, a commission, etc.
What actually changed, when relevant - for updates, you'll see the old value and the new value side by side, so you know exactly what shifted (for example, a status going from "pending" to "approved").
The full details of whatever changed - all the relevant information about that promoter, referral, or commission at that moment.
A timestamp - when it happened.
Alongside all that, FirstPromoter also includes the event's ID and type in the notification's technical headers, which is mostly useful if your team is doing any logging or debugging.
Example Payload
{
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event_type": "promoter.created",
"action": "created",
"entity_type": "promoter",
"entity_id": 12345,
"changes": {},
"data": {
"id": 12345,
"email": "[email protected]",
"name": "Jane Smith",
"cust_id": "cus_abc123",
"balances": {},
"joined_at": "2025-01-15T10:30:00Z",
"profile": {
"id": 98765,
"first_name": "Jane",
"last_name": "Smith",
"website": "https://janesmith.com",
"company_name": "",
"phone_number": "",
"address": "",
"country": "US",
"paypal_email": "",
"avatar": ""
}
},
"timestamp": "2025-01-15T10:30:00Z"
}
If a delivery fails
Nobody's server is up 100% of the time, so FirstPromoter has a built-in safety net:
If your endpoint doesn't respond properly, FirstPromoter automatically retries, waiting a little longer each time (roughly 20 minutes, then 40, then 60, and so on).
By default, it tries 3 times before giving up and marking the delivery as failed
You can see the full history of every attempt, including what your server responded with, right from Settings → Integrations → Webhooks, by clicking into a subscription.
If something failed and you've since fixed the issue, you can manually retry that specific delivery from the same screen, instead of waiting for the automatic schedule.
Testing without waiting for a real event
You don't have to wait for a real referral or sale to see what a notification looks like. When you're setting up a subscription, there's a Run Test button that fires off a sample notification immediately (a real request to your endpoint). This is the fastest way to confirm your setup actually works before it matters.
If notifications aren't showing up
A few quick things to check, in order:
Is the URL correct? A typo or a missing path at the end of the address is one of the most common reasons nothing arrives.
Are the right events selected? It's easy to set up a webhook and forget to actually check the box for the event you care about.
Check the delivery history. Go to Settings → Integrations → Webhooks, click into the subscription, and look at what's actually been attempted; you'll see the status, the response code your server sent back, and any error message.
Try Run Test. If a test notification doesn't arrive either, the problem is almost always on your endpoint's side (wrong URL, server not running, blocking the request) rather than on FirstPromoter.
Test with an external endpoint. Point the webhook at a temporary address like https://webhook.site, copy the URL it gives you, paste it in, and trigger an event. If the request shows up there, FirstPromoter is fine, and the problem's on your end.