Events, webhooks and debugging

Contactivity tells your server what happens on calls through webhooks, keeps a 7-day event log, and records every request it sends you and every error it hits. Paths are relative to https://api.contactivity.io/v1/projects/{project_id}; see the overview.

Native events

Voice apps with param_style: "contactivity" (the default for apps created through this API, see voice-apps.md) send call-control events in the native envelope, and recording and transcription events use it too:

{
  "id": "evt_5f0c…",
  "type": "call.answered",
  "created_at": "2026-10-22T14:03:11.123Z",
  "project_id": "6a1f…",
  "data": {"call_id": "CA…", "parent_call_id": null, "app_id": "app_us1_…", "client_state": "b3JkZXItNDI=",
           "from": "+12125550123", "to": "+14155550100", "direction": "outbound"}
}

data always has call_id, parent_call_id, app_id and client_state; from, to, direction and custom_parameters when known; plus fields of the event (digits, recording ids, ...).

Event types:

New types may be added; ignore types you do not handle. Apps with param_style: "twilio" keep the Twilio/Telnyx-compatible formats (compatibility.md).

Where events go

To the voice app's webhook_url (or the call's webhook_url). Events without a URL of their own go to the project's webhook endpoint, when one is set:

curl -X PUT https://api.contactivity.io/v1/projects/$PROJECT_ID/webhook-endpoint \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/contactivity-events", "event_types": ["call.completed", "call.recording.completed"]}'

url must be a public https:// URL; null or "" turns the endpoint off. event_types empty or missing means all types. Both GET and PUT return {url, event_types, updated_at}. Errors: 400 invalid_parameter (param url, event_types), 400 unknown_parameter.

Verifying signatures

Every webhook, CoXML fetch and AI tool call is signed with Standard Webhooks headers: webhook-id (the event id for native events), webhook-timestamp (Unix seconds) and webhook-signature (v1a,<base64 Ed25519 signature> over {webhook-id}.{webhook-timestamp}.{raw body}). Get the public key from GET /webhook-public-key, reject timestamps more than 5 minutes old, and verify over the raw body. For 24 h after a key rotation the header carries two space-separated entries (new key first); a signature is valid when any entry verifies, which the SDK helpers do:

import { verifyStandardWebhook } from "@contactivity/sdk";
if (!verifyStandardWebhook(publicKey, req.headers, rawBody)) return res.sendStatus(401);

from contactivity_sdk import verify_standard_webhook
if not verify_standard_webhook(public_key, request.headers, raw_body):
    abort(401)

Answer with a 2xx within a few seconds; failed deliveries are retried and show up in /webhook-deliveries.

Event log

GET /events lists the stored events, newest first. The stored copy keeps metadata only (ids, states, causes, times, durations, numbers and media facts); everything else, including transcripts, speech and gather results, digits, AI message history, summaries, client_state and custom parameters, is dropped and the event is marked content_redacted: true. Webhook deliveries carry the full data. Stored events are never deleted: archiving a call, recording or transcription keeps them. Filters: type (one type, or a prefix such as call.*), call_id, created_after, created_before (RFC 3339 or YYYY-MM-DD), limit, starting_after. Each item is the envelope above. GET /event-types lists every event type (any API key of the project).

curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/events?type=call.*&call_id=$CALL_ID" \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY"

Webhook deliveries

GET /webhook-deliveries lists every request Contactivity sent to your URLs, newest first. Filters: status (succeeded = 2xx, failed = other status, connection error or timeout), kind (webhook, coxml, alert), url (exact), call_id, limit, starting_after.

Error debugger

GET /errors lists errors raised while running calls and apps (bad CoXML, failed webhooks, AI agent errors), newest first. Filters: category (coxml, webhook, call, ai_agent, app), call_id, limit, starting_after. Each item: id, created_at, category, code (integer), message, url, call_id.

Alert rules

An alert rule emails people and/or calls a webhook when errors (or an AI agent metric) cross a threshold within a time window, then waits out a cooldown. A project has at most 20 rules.

At least one of emails or webhook_url is required. The rule object has these fields plus id (alr_…), last_fired_at and created_at.

Errors: 400 invalid_parameter (param name, category, codes, threshold, metric, window_minutes, cooldown_minutes, emails, webhook_url, voice_app_id), 400 invalid_request (no emails and no webhook_url, or an AI metric threshold out of range), 400 unknown_parameter, 404 not_found, 409 conflict (already 20 rules).

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/alert-rules \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Webhook failures", "category": "webhook", "threshold": 10, "window_minutes": 5,
       "emails": ["oncall@example.com"]}'