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