Skip to navigation

Inbound call webhook payload for voice agent deployments

The payload Sarvam POSTs to your webhook after each inbound call finishes.
View as Markdown

After an inbound call finishes, Sarvam sends a POST request to your webhook with the call result. Set the target in the deployment’s webhook_config either as an inline url or as a webhook_id referencing a stored webhook config — see Create deployment and Update deployment. Deliveries that use a stored webhook config are signed — see Verifying the delivery.

Payload schema

FieldTypeDescription
app_idstring (required)ID of the agent.
app_versioninteger (required)Version of the agent.
deployment_idstring (required)Deployment this call belongs to.
interaction_idstring (required)Unique identifier for this call interaction. Also used as the attempt_id in delivery records and retry requests.
user_phone_numberstring (required)Phone number of the caller in E.164 format.
agent_phone_numberstring (required)Inbound number the user dialed, in E.164 format.
durationnumberCall duration in seconds. Defaults to 0.0.
final_agent_variablesobject | nullAgent variables at the end of the conversation.
output_agent_variablesobject | nullVariables collected by the agent during the call.
start_datetimestring | nullTimestamp when the call started (ISO 8601 UTC, e.g. 2026-09-01T18:44:15Z).
end_datetimestring | nullTimestamp when the call ended (ISO 8601 UTC, e.g. 2026-09-01T18:44:31Z).
interaction_transcriptarray | nullTranscript of the conversation as a list of turns. Each turn has role ("agent" or "user"), en_text, and optional indic_text.
metadataobject | nullCustom metadata from the webhook configuration.

Example

{
"app_id": "Conversatio-4889d972-cc49",
"app_version": 3,
"deployment_id": "pruthviraj--8430b3a7-dfc1",
"interaction_id": "20260828/8448d531-12:47:17-0f1a2cb7",
"user_phone_number": "+917948229484",
"agent_phone_number": "+918044620704",
"duration": 51.58,
"final_agent_variables": {
"customer_name": "Akul",
"call_disposition": "BUSY_CALL_BACK",
"call_outcome": "busy_callback",
"follow_up_required": true
},
"output_agent_variables": {
"call_outcome": "busy_callback",
"follow_up_required": true
},
"start_datetime": "2026-08-28T07:16:25Z",
"end_datetime": "2026-08-28T07:17:17Z",
"interaction_transcript": [
{ "role": "agent", "en_text": "Hello, am I speaking with Akul?", "indic_text": null },
{ "role": "user", "en_text": "Yes, speaking.", "indic_text": null },
{ "role": "agent", "en_text": "I am calling regarding your loan application.", "indic_text": null }
],
"metadata": { "ref": "crm-lead-42" }
}

Verifying the delivery

When the deployment’s webhook_config references a stored webhook config (webhook_id), every delivery is authenticated with an HMAC signature. The signing secret is returned once, in the response when you create the webhook config — it is never shown again, so store it immediately.

Each signed delivery carries two headers:

HeaderDescription
Sarvam-Signaturesha256=<hex> — HMAC-SHA256 of "<timestamp>.<body>" using your signing secret.
Sarvam-TimestampUnix timestamp in seconds. The same value used inside the signature.

Verify the delivery by recomputing the HMAC over the raw request body (do not re-serialize parsed JSON) and comparing it with the header:

import hmac, hashlib
def verify_delivery(signing_secret, timestamp, raw_body, signature_header):
expected = hmac.new(
signing_secret.encode(),
f"{timestamp}.".encode() + raw_body, # raw request bytes
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature_header)

Notes:

  • Reject deliveries whose Sarvam-Timestamp is older than five minutes to guard against replay.
  • Custom headers set on the webhook config are sent with every delivery. The signature and timestamp headers always win over custom headers with the same name.
  • If the deployment uses an inline url instead of a webhook_id, deliveries are not signed.