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

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 controlBasicConfigurable retries (0–10) per subscription
TimeoutFixed 15 sConfigurable per subscription (1–120 s)
Custom headersNot supportedArbitrary key/value headers
SignatureNoneHMAC-SHA256 on every request
Secret rotationNoRotate any time without downtime

​
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.
​
timeout
number
HTTP request timeout in seconds. Defaults to 30, maximum 120.
​
max_retries
number
How many times to retry a failed delivery before marking it as failed. Defaults to 3, range 0–10.
​
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" }
​
secret_key
string
Auto-generated 64-character hex string used to sign payloads. See Security.

​
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 and signature headers.
  5. Respond with any 2xx status code to acknowledge the delivery.
  6. If the response is not 2xx, the delivery is retried according to your max_retries setting.
Your endpoint must respond within the configured timeout. If it does not respond in time, the attempt counts as a failure and will be retried.