Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firstpromoter.com/llms.txt

Use this file to discover all available pages before exploring further.

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

FeatureLegacy webhooksWebhooks v2
Subscriptions3 hardcoded URLs per campaignUnlimited subscriptions per account
Event typesFixed predefined listDynamic pattern-based selection
Campaign filteringNo — all events always firedSubscribe to specific campaigns
Delivery trackingLimitedFull history with status and response details
Retry controlBasic3 retries by default
TimeoutFixed 15 s30 s by default
Custom headersNot supportedArbitrary key/value headers

​
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.
{ "Authorization": "Bearer my-token", "X-My-Header": "value" }

​
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.