For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook – Call Outcome Integration

VoiceB.ai Webhook – Call Outcome Integration

Webhooks let you receive structured call outcomes, transcripts, and lead data after every call. Use this to:

  • Save conversations to your database

  • Trigger follow-ups or automations

  • Push call results into any system that accepts JSON, in the structure your system expects


🔗 How it Works

  1. Add the Webhook integration to your agent (see the steps below) and enter your endpoint URL.

  2. Choose how VoiceB authenticates to your endpoint (a fixed token or a stored credential) and, optionally, enable signature signing for secure verification.

  3. After every call, VoiceB sends a POST request with the call result to your URL. Use Trigger Conditions to choose which outcomes are sent.

  4. Optionally, turn on a custom body template to send the JSON in your own structure.


How to Add a Webhook Integration

  1. In your VoiceB account, go to Campaigns.

  2. Select the Agent you want to configure.

  3. Once inside the Agent Config (Name, AI Provider, Goal, Script…), scroll down to Integrations.

  4. Click on the “+” button.

  5. Choose Webhook from the list.

  6. You will now see the configuration screen with instructions and examples.


🔑 Authentication

Choose how VoiceB authenticates to your endpoint:

  • Fixed token: a static Bearer token that you type into the settings. It is sent on every request and never expires or refreshes on its own.

  • Stored credential: pick one of the credentials stored for the campaign from a dropdown. VoiceB logs in to your system for you (for example with OAuth2 client credentials or a custom login request) and refreshes the token automatically. No secret is ever shown in the UI. Credentials are the same ones used by Agent Tools, see Credentials.

Use a stored credential when your system requires a login step before every request, so you never have to rotate tokens by hand.


📬 Default Webhook Payload

By default, VoiceB sends the following JSON object. Fields are sent in this order:

These keys are only present on some calls:

  • retry and pendingRetry: when the agent has a retry policy, the call is in a retry chain, or a retry is scheduled.

  • consent: on calls that collected consent (widget and click-to-call).

  • reviewFlag: on calls that were flagged for review.

  • sipHeaders: on calls that came through a SIP trunk.

  • status and collectedData: when the call has no lead.

The call recording URL is never included.


🧩 Custom Body Template (Optional)

By default VoiceB sends the payload above. If your system expects a different JSON structure, you can define your own.

  1. Open the Webhook integration settings.

  2. Turn on Use custom body template.

  3. Write your JSON in the editor. Type {{ to see the available variables with their types, and use them wherever you need a value.

  4. Save. The template must be valid JSON, otherwise it cannot be saved.

Example template:

The body VoiceB sends is this template with the variables filled in. The webhook URL can also contain {{variables}}.

The template root can be a JSON object or an array, for example [ { "id": "{{id}}" } ], if your system expects a list.

Keeping data types

When a value is exactly one variable, for example "messages": "{{transcript}}", VoiceB inserts the variable with its real type: lists stay lists, objects stay objects, and numbers and booleans stay numbers and booleans. In the example above, callId is a number, messages is the transcript as a list, and labels is a list of tag names.

When the variable is mixed with other text, for example "Call {{id}} by {{agent}}", it is inserted as text.

Default values

To use a fallback when a value is missing, empty or null, add || and a default after the variable name. The default must be a valid JSON value.

Variable with default
Default used

{{collectedData.name||"Unknown"}}

text Unknown

{{collectedData.age||0}}

number 0

{{collectedData.optIn||false}}

boolean false

{{collectedData.email||null}}

null

{{tags||[]}}

empty list

{{collectedData||{}}}

empty object

Because the template is itself JSON, a text default placed inside a text value needs escaped quotes:

A default such as {{collectedData.name||Unknown}} (text without quotes) is not valid, and the template cannot be saved until it is fixed.

If you do not set a default and a value is missing, VoiceB uses an empty value of the right type: empty text for text, null for numbers, dates and optional objects, false for booleans, [] for lists and {} for collectedData, sipHeaders and variables. Inside text or in the URL, a missing value becomes an empty string.

Available variables

Variable
Type
Notes

event, agent, from, to, agentPhone, customerPhone, status, type, channelUsed, summary, humanTranscript, language

text

id, previousCallId, nextCallId, previousRetryCallId, nextRetryCallId

number

start, end

date

ISO format

testCall, transferred, inbound

true / false

transcript

list

The parsed conversation messages

tags

list

Tag names

collectedData

object

Also collectedData.<field> for any field of your Data Collection schema

sipHeaders

object

Also sipHeaders.<header>

variables

object

Also variables.<name> for the call's dynamic variables

consent

object

Only on calls with consent. Fields: id, ipAddress, userAgent, origin, documentVerified, createdAt, documents

reviewFlag

object

Only on flagged calls. Fields: id, category, description, flaggedBy, createdAt

retry

object

Only with a retry policy. Fields: attempt, max

pendingRetry

object

Only when a retry is scheduled. Fields: id, attemptNumber, scheduledFor, failureReason

The fields removed from the default payload (linkedCallsIndex, linkedCallsTotal, provider, sessionLegs), the recording URL and the integration sync details are not available as variables.

Custom body templates are available on the post-call webhook only. Pre-call and pre-transfer webhooks work as before.


🛡️ Signature Verification (Optional)

Headers:

Use your signature secret to verify the authenticity of the payload. The signature is computed over the exact body that VoiceB sends. If you use a custom body template, it is computed over the filled-in body.

Always verify the signature against the raw request body as you received it, not against a JSON object that you have parsed and re-serialized, because re-serializing can change spacing and key order and the check will fail.


Trigger Conditions

By setting trigger conditions, you can define specific outcomes that will determine if the integration runs for that call or not. Allowing you to determine which ones ends in your system/CRM


🔍 Monitoring and Resync

Each call shows whether its webhook was delivered (ok) or not (failed). Open the integration drawer to see the Debug Trace, which records failures only. If a call failed, click Resync to send it again once the problem is fixed. Debug traces are visible to organization admins.

If a custom body template cannot be filled in correctly when the call ends, nothing is sent and the call is recorded as a failed sync, so you can fix the template and resync.


If you need help setting this up, reach out to hello@voiceb.ai

Last updated

Was this helpful?