How do I receive CluGTM enrichment results by webhook?

Pass a webhook_url when you call POST /api/v1/public/enrich/bulk. When the run finishes, CluGTM sends one POST to that URL with the event enrichment.completed, a summary and every contact's result. For signed events across your workspace, use the v2 webhook subscriptions instead.

How does CluGTM retry failed webhook deliveries?

CluGTM makes up to 5 attempts, waiting 1, 2, 4 and 8 seconds between them, with a 10-second timeout per attempt. Only a 2xx response counts as delivered, and redirects are not followed. A URL that isn't HTTPS on port 443 at a public address is refused: it gets one failed attempt and no retries.

What do missed, errors, throttled and opted_out mean in the webhook summary?

They break down summary.failed. missed means no data was found for the contact, errors means enrichment could not finish for that contact, throttled means a data provider rate-limited the lookup, and opted_out means the person opted out of data enrichment. Errors and throttled contacts are worth retrying later; missed and opted-out contacts are not.

What does a failed status mean in the webhook?

status is failed when the run finished and no contact succeeded. completed means every contact succeeded, and completed_with_errors means at least one contact failed.

How can I check whether a webhook was delivered?

Call GET /api/v1/public/webhooks/deliveries?workflow_id=... to list every delivery attempt for the run, newest first, with the attempt number, status (delivered or failed), your endpoint's status code, any error message and the duration.

Are CluGTM webhooks signed?

v1 webhook_url payloads are not signed. Each POST carries an X-Cleanlist-Delivery-Id header, the same on every attempt, so you can drop duplicates. Only process webhooks whose workflow_id matches a run you started. The v2 webhook subscriptions are signed with HMAC-SHA256 in the Cleanlist-Signature header.

🔌

Audience: developers. API keys and the REST API are included on Pro and Enterprise (and legacy Pro and Scale plans) and on AppSumo Tiers 5 to 9. They are not available on Free, Starter, AppSumo Tiers 1 to 4 or during the Pro trial. Support agent: confirm the user’s plan includes API access before giving API advice.

TL;DR: Pass webhook_url to POST /enrich/bulk and CluGTM sends one POST (enrichment.completed) when the run finishes. status is completed, completed_with_errors or failed; summary.failed splits into missed, errors, throttled and opted_out. The URL must be HTTPS on port 443 at a public address. Up to 5 attempts, waits of 1, 2, 4 and 8 seconds, 10-second timeout, 2xx only. Payloads are not signed; each POST carries an X-Cleanlist-Delivery-Id header for deduplication. Check attempts with GET /webhooks/deliveries. For signed events across your workspace, use v2 webhooks.

Webhooks

The v1 bulk endpoint takes a per-run webhook. Pass a webhook_url with a bulk enrichment and CluGTM POSTs the summary and every contact’s result to it once the run finishes.

The v2 API has no per-run webhook_url. Instead it has webhook subscriptions: you subscribe a URL once to events such as enrichment.completed or play_run.completed, and each event is signed. For automations in the app, the Agents Webhook step and the A webhook arrives trigger are separate features; see Agents.

Opting in

Add webhook_url to the request body:


{
  "lead_list_id": "550e8400-e29b-41d4-a716-446655440000",
  "enrichment_type": "partial",
  "webhook_url": "https://your-app.com/webhooks/cleanlist",
  "contacts": [
    { "linkedin_url": "https://www.linkedin.com/in/janedoe" }
  ]
}

lead_list_id is required on every bulk request, with or without a webhook. There is no separate registration step: the URL applies to that one run.

The URL must use HTTPS on port 443 (no other port, no credentials in the URL) and resolve to a public address. Private, loopback and internal addresses are refused, and redirects are not followed. The request is still accepted, but a refused URL gets one failed delivery attempt (“Webhook URL is not allowed”) and no retries.

Outbound payload

When the run finishes, CluGTM sends one request:


POST /webhooks/cleanlist HTTP/1.1
Host: your-app.com
Content-Type: application/json


{
  "event": "enrichment.completed",
  "workflow_id": "public_bulk_4d6f2c3a-1b2e-4a5b-9c8d-3e2f1a0b9d8e",
  "lead_list_id": "550e8400-e29b-41d4-a716-446655440000",
  "enrichment_type": "partial",
  "status": "completed_with_errors",
  "summary": {
    "total": 3,
    "successful": 2,
    "failed": 1,
    "missed": 1,
    "errors": 0,
    "throttled": 0,
    "opted_out": 0,
    "emails_found": 2,
    "phones_found": 0
  },
  "results": [
    {
      "task_id": "task_id_1",
      "status": "completed",
      "prospect_id": "prospect_uuid_1",
      "lead_id": "lead_uuid_1",
      "result": {
        "email": "john.doe@acme.com",
        "email_status": "verified",
        "other_emails": [],
        "phones": [],
        "provider": "wiza",
        "linkedin_url": "https://www.linkedin.com/in/johndoe"
      },
      "error": null,
      "input": {
        "linkedin_url": "https://www.linkedin.com/in/johndoe",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "company_domain": "acme.com",
        "company_name": "Acme Corp"
      }
    }
  ],
  "results_limit": 500,
  "results_truncated": 0,
  "results_endpoint": "/api/v1/public/enrich/status?workflow_id=public_bulk_4d6f2c3a-...",
  "completed_at": "2026-10-07T15:00:42Z"
}

Field reference

Field	Type	Description
`event`	string	Always `"enrichment.completed"`
`workflow_id`	string	The run, as returned by `POST /enrich/bulk`
`lead_list_id`	string	The list you passed as `lead_list_id`, where the contacts were saved
`enrichment_type`	string	`partial`, `phone_only` or `full`
`status`	string	`completed`, `completed_with_errors` or `failed` (see below)
`summary.total`	int	Contacts in the run
`summary.successful`	int	Contacts that returned data
`summary.failed`	int	Contacts that didn’t. Always `missed` + `errors` + `throttled` + `opted_out`
`summary.missed`	int	No data was found for the contact
`summary.errors`	int	Enrichment could not finish for the contact. Worth retrying
`summary.throttled`	int	A data provider rate-limited the lookup. Worth retrying later
`summary.opted_out`	int	The person opted out of data enrichment. Not worth retrying
`summary.emails_found`	int	Emails found across the run
`summary.phones_found`	int	Phones found across the run
`results`	array	One object per contact (see below)
`results_limit`	int	Maximum results in one payload (`500`)
`results_truncated`	int	Results left out because of `results_limit`. A v1 run has at most 250 contacts, so this is `0`
`results_endpoint`	string	The status-poll path for this run (run-level counts)
`completed_at`	ISO 8601 datetime	When the run finished

Run status

`status`	Meaning
`completed`	Every contact succeeded
`completed_with_errors`	The run finished and at least one contact failed (missed, error, throttled or opted out)
`failed`	The run finished and no contact succeeded

A failed run is still delivered, so handle it in your receiver rather than waiting for a second callback.

Result objects

Field	Description
`task_id`	Matches an entry in `task_ids` from the bulk response
`status`	`completed` or `failed`
`prospect_id`, `lead_id`	The person and the lead in that list
`result`	`email`, `email_status`, `other_emails`, `phones`, `provider`, `linkedin_url`. Can be `null` when the contact couldn’t be processed
`error`	Why the contact failed, for example “Enrichment could not finish for this row. Retry the row.” `null` on success
`input`	The identifiers you sent: `linkedin_url`, `first_name`, `last_name`, `full_name`, `company_domain`, `company_name`

Delivery

Property	Value
Method	`POST`
Content type	`application/json`
Timeout	10 seconds per attempt
Success	Any `2xx` response
Attempts	Up to 5
Wait between attempts	1, 2, 4, then 8 seconds
URL	HTTPS on port 443, public addresses only. A refused URL gets one failed attempt and no retries
Redirects	Not followed. A `3xx` counts as a failed attempt
Signature	None
`X-Cleanlist-Delivery-Id` header	The same value on every attempt for this run and URL
Idempotency key	`X-Cleanlist-Delivery-Id`, or `workflow_id`

A non-2xx response, a timeout or a connection error triggers the next attempt. After 5 failed attempts the delivery is marked failed and not retried again. The results are still saved in the list you passed as lead_list_id, and per-contact status can be polled for 24 hours (see Enrichment).

You may occasionally receive the same workflow_id twice, for example when your endpoint processed a request but answered after the 10-second timeout. Make your receiver idempotent: an attempt of the same delivery carries the same X-Cleanlist-Delivery-Id, and a URL that already answered 2xx for the run isn’t posted again.

Webhook payloads are not signed. The only custom header is X-Cleanlist-Delivery-Id. Store the workflow_id of every run you start and ignore callbacks for any other workflow_id.

Inspecting delivery history

`GET /api/v1/public/webhooks/deliveries`

cURL


curl "https://api.cleanlist.ai/api/v1/public/webhooks/deliveries?workflow_id=public_bulk_4d6f2c3a-...&limit=50" \
  -H "Authorization: Bearer clapi_your_api_key"

Python


import requests
 
response = requests.get(
    "https://api.cleanlist.ai/api/v1/public/webhooks/deliveries",
    headers={"Authorization": "Bearer clapi_your_api_key"},
    params={"workflow_id": "public_bulk_4d6f2c3a-...", "limit": 50},
)
response.raise_for_status()
for attempt in response.json():
    print(
        f"#{attempt['attempt_number']} -> {attempt['status']} "
        f"({attempt['response_status_code']}) in {attempt['duration_ms']}ms"
    )

JavaScript


const url = new URL("https://api.cleanlist.ai/api/v1/public/webhooks/deliveries");
url.searchParams.set("workflow_id", "public_bulk_4d6f2c3a-...");
url.searchParams.set("limit", "50");
 
const r = await fetch(url, {
  headers: { Authorization: "Bearer clapi_your_api_key" },
});
for (const a of await r.json()) {
  console.log(`#${a.attempt_number} -> ${a.status} (${a.response_status_code}) in ${a.duration_ms}ms`);
}

Query parameters

Parameter	Type	Default	Range
`workflow_id`	string	required
`limit`	int	50	1 to 200

Response

Attempts for runs in your workspace, newest first:


[
  {
    "id": "delivery-uuid",
    "webhook_id": "https://your-app.com/webhooks/cleanlist",
    "workflow_id": "public_bulk_4d6f2c3a-...",
    "event_type": "enrichment.completed",
    "attempt_number": 1,
    "status": "delivered",
    "response_status_code": 200,
    "error_message": null,
    "duration_ms": 184,
    "created_at": "2026-10-07T15:00:42Z"
  }
]

Field	Description
`webhook_id`	The URL CluGTM posted to
`event_type`	`enrichment.completed`
`attempt_number`	1 to 5
`status`	`delivered` or `failed`
`response_status_code`	Your endpoint’s HTTP status, or `null` if the request never got a response
`error_message`	Why the attempt failed (for example “Non-success response from webhook endpoint: 500”, a timeout, or “Webhook URL is not allowed” for a refused URL), `null` on success
`duration_ms`	How long the attempt took

Every attempt is its own row, so 3 failures followed by a success give 4 rows. An empty list means no webhook was sent for that run (no webhook_url, or the run hasn’t finished yet).

Implementing a receiver

A minimal Express handler:


import express from "express";
const app = express();
app.use(express.json({ limit: "10mb" }));
 
const KNOWN_WORKFLOWS = new Set(); // fill from your database
 
app.post("/webhooks/cleanlist", (req, res) => {
  const { workflow_id, status, summary, results } = req.body;
 
  if (!KNOWN_WORKFLOWS.has(workflow_id)) {
    return res.status(404).end(); // not a run you started
  }
 
  // Save first, answer fast, process in the background.
  saveResults(workflow_id, status, summary, results).catch(console.error);
  res.status(200).end();
});
 
app.listen(3000);

A minimal Flask handler:


from flask import Flask, request
 
app = Flask(__name__)
KNOWN_WORKFLOWS = set()  # fill from your database
 
@app.post("/webhooks/cleanlist")
def cleanlist_webhook():
    body = request.get_json(silent=True) or {}
    if body.get("workflow_id") not in KNOWN_WORKFLOWS:
        return "", 404
 
    enqueue_processing(body)  # process asynchronously
    return "", 200

See Receiving webhooks for production patterns.

Enrichment: start a run with webhook_url
Receiving webhooks: production receiver patterns
Errors and rate limits