Call Webhook

When making calls through voicehub platform, widget or API, voicehub allows for sending callbacks to your backend to help you track call status, call recordings and call analysis.

Configuring Webhook through Voicehub

In voicehub, each agent can be configured to send webhook requests per calls. This configuration can be found under API Sidebar menu item as in the next screenshot

In the configuration of webhook, you will have multiple options that need to be configured for the webhook.

1. Webhook URL: This is the endpoint url that the webhook will send POST requests to on your end.

2. Secret: This is any secret key you want to be used for verifying webhook requests. It will be sent through a header on the post request x-webhook-secret

3. Retrying attempts and delays: Requests will be retired couple of times to your end points with delays in milliseconds sepcified in the fields

4. Request timeout also is configurable

Events sent through call webhook

Currently, voicehub triggers three different types of events through the lifecycle of a call.

CallStatusChanged

This event is triggered whenever a change happens to your call status. The payload of the post body contains the following jsonized string, the expected call statuses are listed below

{
      eventType: WebhookEventType.CallStatusChanged,
      timestamp: "Date iso string when event happened",
      eventId: "Unique event Id",
      status: "new call status",
      callId: "call id",
      agentId: "Id of the agent for the call",
      userNumber: "Phone number of the user if the call was voip",
      agentNumber: "Phone number of the agent if the call was voip"
}

For call statuses that are returned from the API, you can expect one of the following

started -> When right when the call is connected
queued -> When call is waiting to be started.
completed -> when call completes
in-progress -> When call is being in progress (user/agent are talking)
failed -> Call failed due to some reason
cancelled -> Call is canceled
unanswered -> If call is not answered by the callee. 
scheduled -> If call request had the schedule At parameter so that it is scheduled for a later time.
busy -> If user is busy, rejected the call while ringing
voicemail -> If call is forwarded to voicemail
hangup -> when user hangsup the call while talking without indicating they are ending the call

RecordingsAvailable

This event is triggered upong having the call voice recordings available. The body of the payload is

{
  eventType: WebhookEventType.RecordingsAvailable,
  timestamp: "Date iso string when event happened",
  eventId: "Unique event Id",
  callId: "call id",
  agentId: "Id of the agent for the call",
  userNumber: "Phone number of the user if the call was voip",
  agentNumber: "Phone number of the agent if the call was voip"
}

AnalysisResultReady

This event is triggered whenever the analysis of the call is available. Callback payload contains a link to fetch the results.

{
  eventType: WebhookEventType.AnalysisResultReady,
  analysisId: "Analysis Id",
  timestamp: "Date iso string when event happened",
  eventId: "Unique event Id",
  callId: "call id",
  analysisResultUrl: 'URL for call analysis fetching',
  agentId: "Id of the agent for the call",
  userNumber: "Phone number of the user if the call was voip",
  agentNumber: "Phone number of the agent if the call was voip"
}

Fetching Call Analysis Result:

Once you receive the AnalysisResultReady event, you can fetch the analysis result using the analysisResultUrl provided in the payload.

This is a GET request that requires your agent API key as a header: x-dq-api-key

curl --location '<analysisResultUrl>' \
--header 'x-dq-api-key: <api-key>' 

Example URL :

curl --location 'https://voicehub.dataqueue.ai/api/v1/call-analysis/e2e/<call-id>' \
--header 'x-dq-api-key: <api-key>'

Example Analysis Result Response:

{
  "callId": "string",
  "transcriptAnalysis": [
    {
      "text": "string",
      "speaker": "user",
      "sentiment": {
        "score": 0,
        "label": "positive",
        "positiveKeywords": [
          "string"
        ],
        "negativeKeywords": [
          "string"
        ]
      },
      "start": 0,
      "end": 0,
      "duration": 0,
      "wps": 0
    }
  ],
  "summary": "string",
  "userSummary": {
    "totalSpeechDuration": 0,
    "totalSilenceDuration": 0,
    "totalInterruptionDuration": 0,
    "wps": 0,
    "sentiment": {
      "score": 0,
      "label": "positive",
      "positiveKeywords": [
        "string"
      ],
      "negativeKeywords": [
        "string"
      ]
    },
    "keyPhrases": {
      "positive": [
        "string"
      ],
      "negative": [
        "string"
      ]
    }
  },
  "assistantSummary": {
    "totalSpeechDuration": 0,
    "totalSilenceDuration": 0,
    "totalInterruptionDuration": 0,
    "wps": 0,
    "sentiment": {
      "score": 0,
      "label": "positive",
      "positiveKeywords": [
        "string"
      ],
      "negativeKeywords": [
        "string"
      ]
    },
    "keyPhrases": {
      "positive": [
        "string"
      ],
      "negative": [
        "string"
      ]
    }
  },
  "totalSummary": {
    "totalSpeechDuration": 0,
    "totalSilenceDuration": 0,
    "totalInterruptionDuration": 0,
    "wps": 0,
    "sentiment": {
      "score": 0,
      "label": "positive",
      "positiveKeywords": [
        "string"
      ],
      "negativeKeywords": [
        "string"
      ]
    },
    "keyPhrases": {
      "positive": [
        "string"
      ],
      "negative": [
        "string"
      ]
    }
  },
  "sentiment": {
    "score": 0,
    "label": "positive",
    "positiveKeywords": [
      "string"
    ],
    "negativeKeywords": [
      "string"
    ]
  },
  "duration": 0,
  "recordingUrls": [
    "string"
  ],
  "mainTopics": [
    "string"
  ],
  "loyaltyIndicators": [
    "string"
  ],
  "extractedVariables": {},
  "empathyScore": 0,
  "resolutionStatus": "solved",
  "userInterruptionsCount": 0,
  "createdAt": "2025-09-23T08:48:59.619Z",
  "updatedAt": "2025-09-23T08:48:59.619Z"
}