Skip to main content

​
Webhooks

Webhook subscriptions let you receive real-time notifications when new people of interest are discovered. This is primarily used by the Zapier integration but can be used by any system that accepts webhook payloads. When a sync completes, Catch The Good Ones sends a POST request to each registered webhook URL with the newly discovered people.

​
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.trackedAccountIdintegerNoOnly send discoveries from this tracked account
filterConfig.savedSearchIdintegerNoOnly send discoveries matching this saved search
filterConfig.sourceTypestringNo"follower" or "liker"
filterConfig.feedbackStatusstringNo"good" or "bad"
filterConfig.matchConfidencestringNo"full" or "maybe"

​
Example

curl -X POST https://www.catchthegoodones.com/api/v1/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/v1/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 people of interest. The payload format is identical to the Get People of Interest response. Payloads are chunked into batches of 50 people per request. Each person is a separate item, so if 120 people 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.