> ## 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 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 | 3 retries by default |
| Timeout | Fixed 15 s | 30 s by default |
| Custom headers | Not supported | Arbitrary key/value headers |

## Setting up a subscription

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

### Subscription fields

<ResponseField name="url" type="string" required>
  The HTTPS endpoint that will receive webhook payloads. Must be a valid URL.
</ResponseField>

<ResponseField name="event_types" type="array" required>
  One or more event type strings to subscribe to. See [Event Types](/webhooks-v2/event-types) for the full list.
</ResponseField>

<ResponseField name="campaign_ids" type="array">
  Limit this subscription to events from specific campaigns. Use `[1]` (the default) to receive events from all campaigns.
</ResponseField>

<ResponseField name="description" type="string">
  Optional human-readable label for this subscription.
</ResponseField>

<ResponseField name="active" type="boolean">
  Enable or pause delivery without deleting the subscription. Defaults to `true`.
</ResponseField>

<ResponseField name="headers" type="object">
  Custom HTTP headers to include on every request. Useful for API keys or authorization tokens your endpoint requires.

  ```json theme={null}
  { "Authorization": "Bearer my-token", "X-My-Header": "value" }
  ```
</ResponseField>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.