Skip to main content
GuidesAPI ReferenceSupport

Webhooks Overview

8x8 CPaaS Voice provides webhook types to notify your application about call events and outcomes. Configure these webhooks at the subaccount level to receive HTTP POST callbacks.

Webhook Types​

VSS — Voice Session Summary​

When to use: End-of-session outcome for monitoring, reporting, retries, and reconciliation.

VSS is sent after a voice session ends with details about the call outcome, duration, participants, and any errors encountered.

What it contains:

  • Session outcome (completed, failed, no-answer, busy, etc.)
  • Call duration and timestamps
  • Participant information
  • Error details (if the session failed)

Payload schemas by product:

General webhook guide:

VCA — Voice Call Action​

When to use: In-call decisions for dynamic callflow control (for example, IVR branching, custom call routing).

VCA is sent during an active call when the platform requires your application to decide the next step. Your endpoint can return a callflow response to control what happens next. Use this to build dynamic voice applications with custom business logic.

References:

VCS — Voice Call Status​

When to use: Real-time call status updates and progress telemetry.

Reference:

VRU — Voice Recording Uploaded​

When to use: Recording availability notifications when call recording is enabled.

Reference:

VNU — Virtual Number Updated​

When to use: Virtual number lifecycle events and configuration changes.

Reference:

Error Codes and Status Codes​

Understanding the difference between error codes and status codes is crucial for effective debugging:

API Response Status Codes​

When you see them: Immediately after making an API request (e.g., Send Callflow API)

What they indicate: Whether the API request was accepted, rejected, or encountered an error

Common scenarios:

  • 200 OK - Request accepted, session created
  • 400 Bad Request - Invalid request payload
  • 401 Unauthorized - Authentication failed
  • 404 Not Found - Invalid subaccount or endpoint

Reference:

Session Error Codes (in VSS webhooks)​

When you see them: In the Voice Session Summary (VSS) webhook payload after a session ends

What they indicate: Why a voice session failed or what happened during the call

Common scenarios:

  • Session completed successfully (no error)
  • Call rejected (busy, no answer, invalid number)
  • Audio playback failed
  • Network or routing errors

References by product:

Key Differences​

TypeTimingSourcePurpose
API Status CodesImmediate (synchronous)API responseValidate request acceptance
Session Error CodesAfter session ends (asynchronous)VSS webhook payloadDiagnose call outcome

Example workflow:

  1. You send a Send Callflow API request → Receive 200 OK status code (request accepted)
  2. Call is placed and fails → Receive VSS webhook with error code -1004 (invalid destination)

Configuration​

Configure webhooks using the Webhooks API (per subaccount):

  • Create webhook: POST /api/v1/subaccounts/{subaccountId}/webhooks
  • List webhooks: GET /api/v1/subaccounts/{subaccountId}/webhooks
  • Delete webhook: DELETE /api/v1/subaccounts/{subaccountId}/webhooks/{webhookType}

API Reference:

Security Best Practices​

  • Use HTTPS endpoints
  • Validate inbound requests (for example, allowlist source IPs if your environment supports it) - See Voice IP Addresses for the list of outbound IPs used by 8x8 Voice services
  • Implement idempotency (assume duplicate deliveries can occur)
  • Return HTTP 200 OK quickly and process asynchronously where possible

Next Steps​

Support Channels​