Webhooks

Events & Payload

Supported event types and webhook payload structure.

Event types

call.requested — visitor starts a call and enters the queue.
call.accepted — a rep accepts the call.
call.canceled — visitor leaves before a rep accepts.
call.missed — no rep accepts before the ring timeout.
call.ended — a call ends.
call.transcript_ready — call transcript is ready.
call.recording_ready — recording has finished uploading.
webhook.test — fired when you use the test endpoint.

Event payload

Every event uses the same envelope:

JSON

{
  "id": "event-uuid",
  "type": "call.ended",
  "createdAt": "2024-01-02T00: 00: 00.0002",
  "organizationId": "org-uuid",
  "data": {
    "call": {
      "id": "call-uuid",
      "status": "ended",
      "mediaType": "video",
      "requestedAt": "2024-01-02T00: 00: 00.0002",
      "acceptedAt": "2024-01-02T00: 00: 10.0002",
      "endedAt": "2024-01-02T00: 00: 35.0002",
      "acceptedBy": "user-uuid",
      "sessionId": "session-uuid",
      "siteId": "site-uuid",
      "visitorFingerprint": "fp",
      "qualificationFlowId": null
    },
    "contact": {
      "identityId": "identity-uuid",
      "fingerprint": "fp",
      "email": "visitor@example.com",
      "phone": "+1 512 555 0100",
      "name": "Visitor Name",
      "lastSeenAt": "2024-01-02T00: 00: 00.0002",
      "location": {
        "city": "Austin",
        "region": "TX",
        "country": "United States",
        "countryCode": "US",
        "timezone": "America/Chicago",
        "latitude": 30.2672,
        "longitude": -97.7431
      }
    },
    "qualificationAnswers": [
      {
        "id": "answer-uuid",
        "questionId": "question-uuid",
        "position": 1,
        "question": {
          "id": "question-uuid",
          "label": "Company size",
          "type": "single_select",
          "required": true,
          "position": 1,
          "options": [
            { "label": "1-10", "value": "1-10" },
            { "label": "11-50", "value": "11-50" }
          ]
        },
        "answer": { "value": "1-10" },
        "createdAt": "2024-01-02T00: 00: 00.0002"
      }
    ],
    "transcript": null,
    "recording": {
      "available": false,
      "videoUrl": null,
      "audioUrl": null,
      "expiresInSeconds": null
    }
  }
}

Notes:

All timestamps are ISO-8601.
contact.location can be null if no geo data is available.
contact.phone is null unless the visitor shared a phone number.
transcript is null until a transcript is available.
recording.available is false until a recording has been saved.
call.ended fires for any call end; use call.canceled or call.missed to distinguish queue exits.
recording.videoUrl and recording.audioUrl are only populated on call.recording_ready, and they are signed URLs.
recording.expiresInSeconds is the URL expiry in seconds.
events on a webhook endpoint acts as a filter. If empty, all event types are delivered.

Delivery behavior

Webhooks are delivered with a POST request.
Requests time out after 8 seconds.
Any 2xx response counts as success.
No automatic retries are sent today.
Use the id field (or X-IC-Id) to dedupe events.

Having issues? hello@converc.com.