Webhooks

Coldreach can send real-time HTTP POST notifications to your server when key events occur. Configure webhook URLs in Coldreach settings to start receiving events. Research Changes reports scheduled-refresh changes rather than every real-world change instantly. First-qualified notifications from initial discovery or refresh are an upcoming change, not yet deployed.

Overview

Webhooks let you react to events in Coldreach without polling the API. When an event fires, Coldreach sends a JSON payload to your configured URL via HTTP POST with a Content-Type: application/json header.

Webhook	Trigger
First Touch	The first email in a sequence is sent to a contact
Positive Reply	A positive reply is received from a contact
Research Changes	Scheduled refresh changes company qualification or a company signal outcome/value; setup, payload, and limits
Outreach Finished	Outreach to a contact is completed for any reason

Setting Up Webhooks

Go to Settings > Developer (for Outreach Finished and Research Changes) or Settings > Notifications (for First Touch and Positive Reply) in the Coldreach app
Find the webhook you want to enable
Click Setup and enter your endpoint URL
Coldreach will send a POST request to your URL whenever the event occurs

Your endpoint must return a 2xx status code. Non-2xx responses are treated as failures.

First Touch Webhook

Triggered when the first email in a sequence is sent to a contact. Useful for syncing outreach activity to your CRM or triggering downstream workflows.

Payload

{
  "fullName": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "jobTitle": "VP of Sales",
  "email": "[email protected]",
  "linkedInURL": "https://linkedin.com/in/janesmith",
  "companyName": "Acme Corp",
  "companyWebsiteURL": "https://acme.com",
  "companyDescription": "Enterprise SaaS platform for...",
  "companyLocation": "San Francisco, CA",
  "campaignId": 123,
  "campaignName": "Series B SaaS Companies",
  "subject": "Quick question about Acme",
  "body": "Hi Jane, I noticed that..."
}

Fields

Field	Type	Description
`fullName`	string	Contact's full name
`firstName`	string	Contact's first name
`lastName`	string	Contact's last name
`jobTitle`	string	Contact's job title
`email`	string	Contact's email address
`linkedInURL`	string	Contact's LinkedIn profile URL
`companyName`	string	Company name
`companyWebsiteURL`	string	Company website URL
`companyDescription`	string	Company description from LinkedIn or website
`companyLocation`	string	Company headquarters location
`campaignId`	number	ID of the campaign that triggered outreach
`campaignName`	string	Name of the campaign
`subject`	string	Email subject line
`body`	string	Email body content

Positive Reply Webhook

Triggered when a contact sends a reply that is classified as positive. This fires for both email and LinkedIn channels.

Payload

{
  "assignmentId": 456,
  "channel": "email",
  "contactEmail": "[email protected]",
  "contactName": "Jane Smith",
  "contactLinkedInUrl": "https://linkedin.com/in/janesmith",
  "companyName": "Acme Corp",
  "companyUrl": "https://acme.com",
  "companyDomain": "acme.com",
  "replyMessage": "Thanks for reaching out! I'd love to learn more...",
  "senderEmail": "[email protected]",
  "campaignId": 123,
  "campaignName": "Series B SaaS Companies"
}

Fields

Field	Type	Description
`assignmentId`	number	Internal assignment ID
`channel`	string	`"email"` or `"linkedin"`
`contactEmail`	string	Contact's email address
`contactName`	string	Contact's full name
`contactLinkedInUrl`	string	Contact's LinkedIn profile URL
`companyName`	string	Company name
`companyUrl`	string	Company website URL
`companyDomain`	string	Company domain (e.g. `acme.com`)
`replyMessage`	string	The reply message body
`senderEmail`	string	Email address that sent the original outreach
`campaignId`	number \| null	ID of the associated campaign
`campaignName`	string	Name of the associated campaign

Outreach Finished Webhook

Triggered when outreach to a contact is completed for any reason. This fires when a contact reaches the end of a sequence, replies, bounces, unsubscribes, or is otherwise removed from active outreach. Covers both email and LinkedIn channels.

Payload

{
  "assignmentId": 789,
  "reason": "last_step_sent",
  "channel": "email",
  "contactEmail": "[email protected]",
  "contactName": "Jane Smith",
  "contactLinkedInUrl": "https://linkedin.com/in/janesmith",
  "companyName": "Acme Corp",
  "companyUrl": "https://acme.com",
  "companyDomain": "acme.com",
  "campaignId": 123,
  "campaignName": "Series B SaaS Companies"
}

Fields

Field	Type	Description
`assignmentId`	number	Internal assignment ID
`reason`	string	Why outreach ended (see Reasons below)
`channel`	string	`"email"` or `"linkedin"`
`contactEmail`	string	Contact's email address
`contactName`	string	Contact's full name
`contactLinkedInUrl`	string	Contact's LinkedIn profile URL
`companyName`	string	Company name
`companyUrl`	string	Company website URL
`companyDomain`	string	Company domain (e.g. `acme.com`)
`campaignId`	number \| null	ID of the associated campaign
`campaignName`	string	Name of the associated campaign

Reasons

Reason	Description
`last_step_sent`	All steps in the sequence have been sent
`replied`	Contact replied to an outreach message
`bounced`	Email bounced
`unsubscribed`	Contact unsubscribed
`messaging_blocked`	LinkedIn messaging was blocked
`existing_conversation`	An existing LinkedIn conversation was detected
`already_connected`	The LinkedIn sequence was configured to stop when an existing first-degree connection was detected
`invitation_withdrawn`	LinkedIn invitation was withdrawn (final step)

Research Changes Webhook

Use Research Changes to notify your server when scheduled refresh changes a company's qualification against campaign company criteria or a company signal's outcome/value. Configure the organization destination, then enable Research change webhook in each campaign's Notifications menu.

See Monitor named companies for company-list import, research setup, the research-changed payload, and delivery limits. Failures and wording-only changes do not notify. First-qualified notifications are not deployed yet; the upcoming change covers initial discovery or refresh first establishing overall company qualification, not a positive individual signal alone. Initial unqualified, failed, or partial research stays silent. A process crash before enqueue can lose a change; delivery is not a lossless history or an exactly-once guarantee.

Best Practices

Use HTTPS — Always use an HTTPS endpoint for security.
Respond quickly — Return a 2xx response within a few seconds. Process the payload asynchronously if needed.
Handle duplicates — In rare cases, the same event may be delivered more than once. For outreach events, use assignmentId or campaignId + email as an idempotency key. For Research Changes, use eventId.
Validate payloads — Check that incoming requests contain the expected fields before processing.