> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Callbacks

> Receive async results when connector processing completes

When you [import connectors](/api-reference/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.

<Note>
  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.
</Note>

```json theme={null}
{
  "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:

```json theme={null}
"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.

```json theme={null}
// 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:

```json theme={null}
{
  "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"
}
```

<Info>
  See the full webhook payload schema in the [OpenAPI spec](/api-reference/introduction).
</Info>