Skip to main content
Webhooks v2 is a complete rewrite of the FirstPromoter webhook system. Instead of a fixed set of webhook URLs per campaign, you can now create multiple independent subscriptions with fine-grained control over which events and campaigns trigger them.

​
What’s new in v2

​
Setting up a subscription

Navigate to Settings → Integrations → Webhooks and click Add new webhook.

​
Subscription fields

​
url
string
required
The HTTPS endpoint that will receive webhook payloads. Must be a valid URL.
​
event_types
array
required
One or more event type strings to subscribe to. See Event Types for the full list.
​
campaign_ids
array
Limit this subscription to events from specific campaigns. Use [1] (the default) to receive events from all campaigns.
​
description
string
Optional human-readable label for this subscription.
​
active
boolean
Enable or pause delivery without deleting the subscription. Defaults to true.
​
headers
object
Custom HTTP headers to include on every request. Useful for API keys or authorization tokens your endpoint requires.

​
How delivery works

  1. An event occurs in your account (e.g., a referral is created).
  2. FirstPromoter checks your active subscriptions for matching event types and campaign filters.
  3. A delivery record is created for each matching subscription and dispatched asynchronously.
  4. Your endpoint receives a POST request with a JSON payload.
  5. Respond with any 2xx status code to acknowledge the delivery.
  6. If the response is not 2xx, the delivery is automatically retried.