Skip to main content

​
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

Register a webhook URL to receive notifications.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer ctgo_your_api_key_here
Content-TypeYesapplication/json

​
Body

FieldTypeRequiredDescription
targetUrlstringYesThe URL to receive webhook POST requests
filterConfigobjectNoOptional filters to narrow which discoveries trigger the webhook
filterConfig.streamIdintegerNoOnly send leads from this campaign
filterConfig.accountIdintegerNoOnly send leads from this tracked account
filterConfig.sourceTypestringNo"follower" or "liker"
filterConfig.feedbackStatusstringNo"good" or "bad"
filterConfig.matchConfidencestringNo"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

HeaderRequiredDescription
AuthorizationYesBearer ctgo_your_api_key_here
Content-TypeYesapplication/json

​
Body

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