Webhooks

API v2 can push events to your server. You subscribe a URL to the event types you care about, and CluGTM POSTs every event of those types in your workspace to it, signed so you can check it came from CluGTM.

A subscription receives every event of its types in the workspace, whoever caused it, so managing subscriptions takes admin:api_keys, the scope that manages the workspace’s credentials. These endpoints are in the served OpenAPI spec but not in the SDKs yet; call them over HTTP.

Events

Dry runs, sample runs and cancelled play runs send nothing.

Subscribe

POST /webhooks

Scope: admin:api_keys · Returns 201

Other fields are refused with 422 validation_error.

curl -X POST https://api.cleanlist.ai/api/v2/webhooks \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/cleanlist",
    "events": ["play_run.completed", "reply.received"]
  }'

{
  "webhook_id": "3f1c2a9b-6d7e-4f80-9a1b-2c3d4e5f6a7b",
  "url": "https://hooks.example.com/cleanlist",
  "events": ["play_run.completed", "reply.received"],
  "created_at": "2026-11-12T15:00:00Z",
  "secret": "whsec_..."
}

The URL is checked when you subscribe and again before every delivery. Private, loopback, link-local and cloud metadata addresses, other ports, a user:password in the URL and hosts that don’t resolve are refused with 422 validation_error (details.field: "url").

A workspace can have up to 10 active subscriptions. Another POST /webhooks returns 409 webhook_limit_reached.

List subscriptions

GET /webhooks

Scope: admin:api_keys

Returns the workspace’s active subscriptions as {"webhooks": [{webhook_id, url, events, created_at}]}. Secrets aren’t included.

Remove a subscription

DELETE /webhooks/{webhook_id}

Scope: admin:api_keys

Stops sending events to the subscription and returns {"webhook_id": "...", "deleted": true}. Its delivery log stays. An id that isn’t an active subscription in this workspace returns 404 webhook_not_found.

What you receive

Each event is one POST with Content-Type: application/json:

{
  "id": "evt_6c1f0e4a-9b2d-5c3e-8f7a-1b2c3d4e5f60",
  "type": "play_run.completed",
  "created_at": "2026-11-12T15:04:05.123456+00:00",
  "organization_id": "org_2xyz...",
  "data": {
    "run_id": "8f0c2d6e-...",
    "playbook_id": "1a2b3c4d-...",
    "status": "completed_with_errors",
    "records_total": 120,
    "records_completed": 117,
    "records_failed": 3,
    "credits_used": 41.6
  }
}

The event id is derived from the workspace, the type and the data, so the same event emitted twice is delivered once.

data by event

Use the ids to read more: a run’s records with GET /gtm-runs/{run_id}/records, an enrichment with GET /enrichment/status/{workflow_id}, a card with POST /actions/confirm.

Verifying the signature

Cleanlist-Signature is t=<unix seconds>,v1=<hex digest>. The digest is HMAC-SHA256, keyed with your whsec_ secret, over the timestamp, a period and the raw request body: "<t>.<raw body>".

1. Split the header on , and read t and v1.
2. Compute HMAC-SHA256 of t + "." + raw_body with the secret, and hex-encode it.
3. Compare it to v1 in constant time. Reject the request if it differs.

Each attempt is signed when it is sent, so you can also refuse a timestamp that is more than a few minutes old.

import crypto from "node:crypto";
import express from "express";
 
const SECRET = process.env.CLEANLIST_WEBHOOK_SECRET; // whsec_...
const app = express();
 
// Keep the raw bytes: the signature covers the body exactly as sent.
app.post("/hooks/cleanlist", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Cleanlist-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${parts.t}.${req.body.toString("utf8")}`)
    .digest("hex");
 
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();
  }
 
  const event = JSON.parse(req.body);
  // Save it, answer fast, process in the background.
  res.status(200).end();
});

import hashlib
import hmac
import os
 
from flask import Flask, request
 
SECRET = os.environ["CLEANLIST_WEBHOOK_SECRET"]  # whsec_...
app = Flask(__name__)
 
@app.post("/hooks/cleanlist")
def cleanlist_hook():
    header = request.headers.get("Cleanlist-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    raw = request.get_data()  # the raw bytes, not re-serialized JSON
    expected = hmac.new(
        SECRET.encode(), parts.get("t", "").encode() + b"." + raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        return "", 401
 
    event = request.get_json()
    # Save it, answer fast, process in the background.
    return "", 200

Delivery and retries

A subscription you remove before an event is sent gets nothing.

A receiver can still see the same event twice, for example when it answered 2xx but the delivery wasn’t recorded. Treat X-Cleanlist-Delivery-Id, or the event id, as an idempotency key. For the rest of a production receiver (answer fast, process in the background, decide what an outage should do), see Receiving webhooks.

Delivery log

GET /webhooks/deliveries

Scope: none (any valid credential)

Lists delivery attempts, newest first. For an event from a subscription, pass the event id (evt_...) as workflow_id; each row’s webhook_id is the subscription’s id.

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

[
  {
    "id": "b7e1...",
    "webhook_id": "3f1c2a9b-6d7e-4f80-9a1b-2c3d4e5f6a7b",
    "workflow_id": "evt_6c1f0e4a-...",
    "event_type": "play_run.completed",
    "attempt_number": 1,
    "status": "delivered",
    "response_status_code": 200,
    "error_message": null,
    "duration_ms": 184,
    "created_at": "2026-11-12T15:04:05Z"
  }
]

Each POST is one row, with status delivered or failed. This is the v1 delivery log on v2: pass a legacy v1 run’s workflow_id to see its webhook_url attempts.

Errors

See Errors & Rate Limits for every code.

Related

• Receiving webhooks
• Actions and approval cards
• GTM Agents API
• Polling & async results
• Authentication & scopes