Webhooks & idempotency.

Three event types can be subscribed per endpoint:

export.ready             a verified export finished building (job_id, totals, download path)
verification.completed   a single-email verification finished (email, status, deliverable)
segment.new_matches      a saved filtered list gained new matching records (list_id, new_matches)

Works with your session (JWT) at /api/webhooks or with an API key (ag_live_*) at /api/mcp/webhooks — same payloads either way.

POST https://argorant.com/api/mcp/webhooks
Authorization: Bearer <your API key>

{ "url": "https://example.com/hooks/argorant",
  "events": ["export.ready", "verification.completed"] }

→ { "id": "12", "secret": "whsec_…", ... }   # secret is shown ONCE — store it

List with GET, remove with DELETE /api/mcp/webhooks/{id}, and queue a sample delivery with POST /api/webhooks/{id}/test. Up to 10 active webhooks per account.

POST <your url>
Content-Type: application/json
X-Argorant-Event: export.ready
X-Argorant-Delivery: 8841
X-Argorant-Signature: sha256=<hex>

{ "event": "export.ready",
  "delivery_id": "8841",
  "created_at": "2026-06-10T09:14:03+00:00",
  "data": { "job_id": 123, "status": "done",
            "total_rows": 500, "verified_rows": 463,
            "download_api_path": "/api/mcp/exports/123/download" } }

The signature is an HMAC-SHA256 of the raw request body using your whsec_ secret. Compare in constant time:

# Python
import hmac, hashlib

def verify(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

// Node
const crypto = require("crypto");

function verify(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

A delivery counts as accepted on any 2xx response within 10 seconds. Anything else is retried with backoff — 1 min, 5 min, 30 min, 2 h, 6 h — then marked failed. Endpoints that fail 50 deliveries in a row are disabled automatically; recreate the webhook to re-enable. Use X-Argorant-Delivery to deduplicate retried events.

Creation endpoints (/api/mcp/exports/create, /api/mcp/lists/create, /api/mcp/lists/{id}/export) accept an optional Idempotency-Key header. Replays with the same key return the original response — no duplicate job, no double-billing:

POST https://argorant.com/api/mcp/exports/create
Authorization: Bearer <your API key>
Idempotency-Key: order-2026-06-10-001

{ "filters": { "q": "fintech CFOs", "country": "Germany" }, "limit": 500 }

# Retried with the same key → identical response + "idempotent_replay": true