Webhooks v2 Overview

Subscribe to real-time events from your FirstPromoter account with the new webhooks system.

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

Feature	Legacy webhooks	Webhooks v2
Subscriptions	3 hardcoded URLs per campaign	Unlimited subscriptions per account
Event types	Fixed predefined list	Dynamic pattern-based selection
Campaign filtering	No — all events always fired	Subscribe to specific campaigns
Delivery tracking	Limited	Full history with status and response details
Retry control	Basic	Configurable retries (0–10) per subscription
Timeout	Fixed 15 s	Configurable per subscription (1–120 s)
Custom headers	Not supported	Arbitrary key/value headers
Signature	None	HMAC-SHA256 on every request
Secret rotation	No	Rotate 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.