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

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

{
  "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

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

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

{
  "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 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.

Getting Started

Account

Streams (campaigns)

Leads

Tracked Accounts

Segments

Sync runs (flat)

DM Templates

Notifications

Webhooks

Lookups (Chrome extension)

Webhooks

Webhooks

Headers

Body

Example

Response

Notes

Unsubscribe

Headers

Body

Example

Response

Webhook payload format

​Webhooks

​Subscribe

​Headers

​Body

​Example

​Response

​Notes

​Unsubscribe

​Headers

​Body

​Example

​Response

​Webhook payload format

Webhooks

Subscribe

Headers

Body

Example

Response

Notes

Unsubscribe

Headers

Body

Example

Response

Webhook payload format