adaptcxadaptcx

Appearance

Webhooks ​

Webhooks send an HTTP POST to your server when significant events happen in AdaptCX. Alternative to polling for updates.

Common uses ​

  • Conversation resolved — sync outcome to your CRM
  • Handoff initiated — page your on-call agent from a chatbot
  • User signed up — trigger your onboarding email flow
  • Wrap-up submitted — write agent notes back to your ticketing system
  • PII flagged — alert your compliance team
  • Billing threshold reached — internal budget alert

Setup ​

Tenant Admin → Integrations → Webhooks → Add Webhook:

  • Name — human label
  • URL — your endpoint (must be HTTPS, publicly accessible)
  • Event types — which events to subscribe to (see Events)
  • Signing secret — auto-generated; used to verify payload authenticity (see Signature)
  • Active — enable/disable

Save; the platform verifies your endpoint by sending a test event. Your endpoint must respond with 2xx within 5 seconds.

Payload shape ​

Every webhook POST has this structure:

json
{
  "event": "conversation.resolved",
  "event_id": "evt_xxx",
  "tenant_id": "tenant_xxx",
  "timestamp": "2026-07-26T14:35:12Z",
  "data": {
    ...event-specific payload...
  }
}

Headers:

  • Content-Type: application/json
  • X-AdaptCX-Signature: <hmac-sha256> — see Signature
  • X-AdaptCX-Event: <event_name>
  • X-AdaptCX-Delivery: <delivery_id> — unique per delivery attempt (idempotency key)

Response ​

Your endpoint should respond with:

  • 2xx — delivery successful; no retry
  • 4xx (except 429) — client error; no retry (fix your endpoint + wait for the next event)
  • 429 or 5xx — server error / rate limit; AdaptCX retries with exponential backoff

Timeout: 5 seconds. Slow responses count as delivery failure and trigger retry.

Retries ​

Failed deliveries retry with exponential backoff:

  • Attempt 1: immediate
  • Attempt 2: 30 seconds later
  • Attempt 3: 5 minutes later
  • Attempt 4: 30 minutes later
  • Attempt 5: 2 hours later
  • Give up after 5 attempts; the delivery is marked failed

Delivery status visible in Tenant Admin → Webhooks → [webhook] → Delivery Log.

Idempotency ​

Use X-AdaptCX-Delivery as an idempotency key. AdaptCX may retry a delivery your endpoint already accepted — dedupe by delivery ID.

Delivery log ​

Every delivery (success or failure) is logged:

  • Event type
  • Timestamp
  • Attempt count
  • Response status + body (truncated to 1 KB)

Retention: 30 days.

Access the log in Tenant Admin → Webhooks → [webhook] → Delivery Log or via /api/v1/webhooks/<id>/deliveries.

Filtering ​

Webhook subscriptions can filter by event attributes:

Event: conversation.resolved
Filter:
  channel = "voice"
  bot_id in [bot_xxx, bot_yyy]

Only conversations matching the filter trigger the webhook. Reduces noise if you only care about a subset.

Testing ​

Tenant Admin → Webhooks → [webhook] → Send Test Event — sends a synthetic event to your endpoint. Useful for verifying signature validation and payload parsing.

Security ​

  • HTTPS required — plaintext HTTP endpoints are rejected
  • Signing secret — verify every payload using Signature. Do NOT skip verification; unsigned webhooks are trivially spoofable.
  • IP allowlisting — AdaptCX webhooks originate from a documented IP range. Add to your firewall allowlist if needed.
  • No sensitive data in URLs — put credentials in headers or signing verification, not in URL query params (they get logged in web-server logs).

See also ​

  • Signature — payload authenticity verification
  • Events — full catalog of webhook events

AdaptCX — product documentation

© AdaptCX