Webhook Callbacks

When you import connectors with a webhook_url, Clustr sends a POST request to your URL once processing completes.

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.2
  },
  "results": [
    {
      "client": {
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "linkedin_url": "https://www.linkedin.com/in/john-doe",
        "record_id": "CRM_12345",
        "owner_email": "alice@company.com",
        "job_title": "VP of Sales",
        "company_name": "Acme Corp"
      },
      "opportunities": [
        {
          "opportunity_id": "opp_abc123",
          "prospect": {
            "name": "Jane Smith",
            "linkedin_url": "https://www.linkedin.com/in/jane-smith",
            "job_title": "CTO",
            "company_name": "Target Inc"
          },
          "company": {
            "name": "Target Inc",
            "domain": "target-inc.com",
            "industry": "Technology",
            "employee_count": "501-1000"
          },
          "relationship": {
            "confidence_score": 85.5,
            "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
            }
          },
          "is_target_company": true
        }
      ]
    }
  ],
  "custom": {
    "your_field": "value"
  },
  "timestamp": "2025-03-15T14:30:00Z"
}

Full engagement history

Pass "full_history": true in the import request to include detailed engagement history in the webhook response:

"engagement": {
  "total_engagements": 3,
  "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/...",
      "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" 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": 0
  },
  "error": {
    "code": "PROCESSING_ERROR",
    "message": "Failed to process contacts",
    "details": "Additional error context"
  },
  "timestamp": "2025-03-15T14:30:00Z"
}

See the full webhook payload schema in the OpenAPI spec.

Getting Started

Competitor Monitoring

Integrations

Webhook Callbacks

Payload format

Full engagement history

Custom data passthrough

Error payloads

​Payload format

​Full engagement history

​Custom data passthrough

​Error payloads

Payload format

Full engagement history

Custom data passthrough

Error payloads