> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catchthegoodones.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Register and manage webhook subscriptions for real-time notifications

# Webhooks

Webhook subscriptions let you receive real-time notifications when new leads are discovered. Primarily used by the Zapier integration but works with any system that accepts webhook POSTs.

When a sync completes, Catch The Good Ones sends a POST request to each registered webhook URL with the newly discovered leads.

**Filter changes in v2 amendment-12**: `segmentId` has been removed (segments are not first-class in the public filter surface); `streamId` is the new way to filter by campaign. `trackedAccountId` renamed to `accountId`. Existing subscriptions with the old `segmentId` filter silently match nothing post-deploy - re-subscribe with `streamId` if you want filtering.

## Subscribe

<api method="POST" path="https://www.catchthegoodones.com/api/v2/webhooks/subscribe" />

Register a webhook URL to receive notifications.

### Headers

| Header          | Required | Description                     |
| --------------- | -------- | ------------------------------- |
| `Authorization` | Yes      | `Bearer ctgo_your_api_key_here` |
| `Content-Type`  | Yes      | `application/json`              |

### Body

| Field                          | Type    | Required | Description                                                      |
| ------------------------------ | ------- | -------- | ---------------------------------------------------------------- |
| `targetUrl`                    | string  | Yes      | The URL to receive webhook POST requests                         |
| `filterConfig`                 | object  | No       | Optional filters to narrow which discoveries trigger the webhook |
| `filterConfig.streamId`        | integer | No       | Only send leads from this campaign                               |
| `filterConfig.accountId`       | integer | No       | Only send leads from this tracked account                        |
| `filterConfig.sourceType`      | string  | No       | `"follower"` or `"liker"`                                        |
| `filterConfig.feedbackStatus`  | string  | No       | `"good"` or `"bad"`                                              |
| `filterConfig.matchConfidence` | string  | No       | `"high"` (high fit lead) or `"medium"` (medium fit lead)         |

### Example

```bash theme={null}
curl -X POST https://www.catchthegoodones.com/api/v2/webhooks/subscribe \
  -H "Authorization: Bearer ctgo_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/", "filterConfig": {"sourceType": "follower"}}'
```

### Response

```json theme={null}
{
  "id": 1
}
```

Returns the subscription ID. Save this - you need it to unsubscribe.

### Notes

* Subscribing the same URL twice updates the filter config (idempotent).
* Different URLs can have different filter configs, so you can set up multiple Zaps with different filters.

***

## Unsubscribe

<api method="DELETE" path="https://www.catchthegoodones.com/api/v2/webhooks/subscribe" />

Remove a webhook subscription.

### Headers

| Header          | Required | Description                     |
| --------------- | -------- | ------------------------------- |
| `Authorization` | Yes      | `Bearer ctgo_your_api_key_here` |
| `Content-Type`  | Yes      | `application/json`              |

### Body

| Field | Type    | Required | Description                                              |
| ----- | ------- | -------- | -------------------------------------------------------- |
| `id`  | integer | Yes      | The subscription ID returned from the subscribe endpoint |

### Example

```bash theme={null}
curl -X DELETE https://www.catchthegoodones.com/api/v2/webhooks/subscribe \
  -H "Authorization: Bearer ctgo_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'
```

### Response

```json theme={null}
{
  "success": true
}
```

Unsubscribing a non-existent subscription returns 200 (idempotent).

***

## Webhook payload format

When a sync completes, each registered webhook URL receives a POST request with an array of leads. The payload format is identical to the [List leads](/api-reference/list-leads) response.

Payloads are chunked into batches of 50 leads per request. Each lead is a separate item, so if 120 leads are discovered, you receive 3 webhook calls (50 + 50 + 20).

Delivery retries up to 3 times with exponential backoff if the target URL is unreachable.