Webhook Callbacks

When you import connectors with a webhook_url, Clustr sends a POST request to your URL once processing completes. If your workspace already has imports in progress, a new job may be queued before it starts, so its webhook can arrive later than usual. Nothing is lost while it waits, and Get Job Status shows QUEUED until it begins.

Payload format

The webhook payload contains the full results for all processed connectors.

Each result names the imported connector under the client key. That key is part of the existing webhook contract and is unchanged by the contacts → connectors rename on the import endpoint.

{
  "status": "completed",
  "job_id": "job_abc123",
  "batch_id": "batch_xyz789",
  "summary": {
    "total_processed": 2,
    "total_opportunities": 15,
    "processing_time_seconds": 45
  },
  "results": [
    {
      "client": {
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "linkedin_url": "https://www.linkedin.com/in/john-doe",
        "linkedin_id": "john-doe",
        "record_id": "CRM_12345",
        "owner_email": "alice@company.com",
        "connector_tags": ["Friend"],
        "job_title": "VP of Sales",
        "company_name": "Acme Corp",
        "location": "Paris, Île-de-France, France",
        "country": "France",
        "seniority_level": "high"
      },
      "opportunities": [
        {
          "opportunity_id": "opp_abc123",
          "prospect": {
            "name": "Jane Smith",
            "first_name": "Jane",
            "last_name": "Smith",
            "linkedin_url": "https://www.linkedin.com/in/jane-smith",
            "linkedin_id": "jane-smith",
            "job_title": "CTO",
            "company_name": "Target Inc",
            "location": "London, England, United Kingdom",
            "country": "United Kingdom",
            "seniority_level": "high"
          },
          "company": {
            "name": "Target Inc",
            "linkedin_url": "https://www.linkedin.com/company/target-inc",
            "linkedin_numeric_id": "12345678",
            "domain": "target-inc.com",
            "industry": "Technology",
            "employee_count": "501-1000",
            "revenue": "100m-200m"
          },
          "relationship": {
            "confidence_score": 86,
            "total_overlap_months": 24,
            "shared_experience": {
              "company_name": "Previous Corp",
              "overlap_months": 24,
              "client_role": "Sales Director",
              "prospect_role": "Head of Engineering",
              "is_current": false
            },
            "shared_education_experience": {
              "institution_name": "HEC Paris",
              "overlap_months": 18
            },
            "engagement": {
              "total_engagements": 3,
              "last_engagement_date": "2025-03-15"
            }
          },
          "is_target_company": true
        }
      ]
    }
  ],
  "custom": {
    "your_field": "value"
  },
  "timestamp": "2025-03-15T14:30:00Z"
}

Fields

Person (`client` and `prospect`)

Field	Type	Description
`name`	string	Full name. Always present.
`first_name`, `last_name`	string	Name parts.
`linkedin_url`	string	LinkedIn profile URL.
`linkedin_id`	string	LinkedIn public identifier, the vanity slug after `/in/` in `linkedin_url`. For example `john-doe` for `https://www.linkedin.com/in/john-doe`.
`record_id`	string	Client only. The `record_id` you sent for this connector in the import request.
`owner_email`	string	Client only. The `owner_email` you sent for this connector in the import request.
`connector_tags`	string[]	Client only. The `connector_tag` you sent for this connector in the import request.
`job_title`	string	Current job title.
`company_name`	string	Current employer.
`location`	string	Location of the current position.
`country`	string	Country in title case, for example `United Kingdom`.
`seniority_level`	string	`high`, `mid` or `low`.

Every person field except name is left out when it has no value.

Company

The prospect’s current company. The whole company object is left out when Clustr has no company for the prospect. When it is present, every field below is included, set to "" when unknown.

Field	Type	Description
`name`	string	Company name.
`linkedin_url`	string	LinkedIn company page URL. The company’s vanity name is the slug after `/company/`.
`linkedin_numeric_id`	string	LinkedIn numeric company ID, for example `"12345678"`. Sent as a string.
`domain`	string	Company domain, for example `target-inc.com`.
`industry`	string	Industry.
`employee_count`	string	Employee range, for example `501-1000`.
`revenue`	string	Revenue range, for example `100m-200m`.

Relationship

Field	Type	Description
`confidence_score`	number	Confidence from 0 to 100, as a whole number.
`total_overlap_months`	number	Total months the client and prospect overlapped, as a whole number.
`shared_experience`	object	The main company they shared: `company_name`, `overlap_months`, `client_role`, `prospect_role`, `is_current`.
`shared_education_experience`	object	The main school they shared: `institution_name`, `overlap_months`. Left out when there is none.
`engagement`	object	`total_engagements` and `last_engagement_date`. Left out when there are no engagements.

summary.processing_time_seconds is rounded to whole seconds.

Full history

Pass "full_history": true in the import request to add each relationship’s full history to the webhook payload:

relationship.shared_experience_history: every company they shared, in the same shape as shared_experience.
relationship.shared_education_experience_history: every school they shared, in the same shape as shared_education_experience.
relationship.engagement.history: every engagement, with duplicates removed. total_engagements then counts the entries in history.

"engagement": {
  "total_engagements": 2,
  "last_engagement_date": "2025-03-15",
  "history": [
    {
      "type": "PROSPECT_LIKED",
      "date": "2025-03-15",
      "link": "https://linkedin.com/...",
      "source": "linkedin"
    },
    {
      "type": "PROSPECT_COMMENTED",
      "date": "2025-02-10",
      "text": "Great insight!",
      "link": "https://linkedin.com/...",
      "context": "Post about sales hiring",
      "source": "linkedin"
    }
  ]
}

Possible engagement types: PROSPECT_COMMENTED, PROSPECT_LIKED, PROSPECT_REACTED, PROSPECT_RECOMMENDED, CLIENT_COMMENTED, CLIENT_LIKED, CLIENT_RECOMMENDED.

Custom data passthrough

Any data you send in the custom field of the import request is passed through to the webhook payload unchanged. Use this to correlate webhook responses with your internal records.

// Import request
{
  "connectors": [...],
  "webhook_url": "https://your-webhook.com/endpoint",
  "custom": {
    "crm_batch_id": "batch_001",
    "triggered_by": "daily-sync"
  }
}

// Webhook response includes it unchanged
{
  "status": "completed",
  "job_id": "job_abc123",
  ...
  "custom": {
    "crm_batch_id": "batch_001",
    "triggered_by": "daily-sync"
  }
}

Error payloads

When processing fails, status is "failed", results is left out and an error object is included:

{
  "status": "failed",
  "job_id": "job_abc123",
  "batch_id": "batch_xyz789",
  "summary": {
    "total_processed": 0,
    "total_opportunities": 0,
    "processing_time_seconds": 12
  },
  "error": {
    "code": "PROCESSING_ERROR",
    "message": "Job processing failed",
    "details": "Additional error context"
  },
  "timestamp": "2025-03-15T14:30:00Z"
}

`error.code`	`status`	Meaning
`PROCESSING_ERROR`	`failed`	The import job failed.
`FETCH_OPPORTUNITIES_ERROR`	`completed`	The job finished but its results could not be loaded. `results` is left out.

See the full webhook payload schema in the OpenAPI spec.

Getting Started

Views & Workflows

Competitor Monitoring

Integrations

CRM Cleaning

Webhook Callbacks

Payload format

Fields

Person (`client` and `prospect`)

Company

Relationship

Full history

Custom data passthrough

Error payloads

​Payload format

​Fields

​Person (client and prospect)

​Company

​Relationship

​Full history

​Custom data passthrough

​Error payloads

Payload format

Fields

Person (`client` and `prospect`)

Company

Relationship

Full history

Custom data passthrough

Error payloads