Webhooks - RevRing AI Documentation

Webhooks allow RevRing to communicate with your systems before and after phone calls, enabling deep integration with your CRM, databases, and business logic.

Webhook Types

RevRing supports two types of webhooks:

Pre-Call Webhooks: Called before an inbound call is answered, allowing you to personalize the agent’s behavior
Post-Call Webhooks: Called after any call ends, providing complete call details including transcript and recording

Pre-Call Webhooks

Pre-call webhooks enable dynamic customization of agent behavior based on caller information. Before answering an inbound call, RevRing sends caller details to your webhook and uses the response to personalize the conversation.

When to Use

Look up caller information in your CRM
Customize greetings based on customer status or history
Route calls differently based on caller context
Apply business hours logic or special handling
Personalize the agent’s knowledge with customer-specific data

Configuration

Navigate to your agent’s Advanced tab

Set the Pre-call Webhook URL:

https://api.yourcompany.com/webhooks/pre-call

Click Save

Pre-call webhooks only apply to inbound calls. Outbound calls receive variables directly via the API when the call is sent.

Request Format

When an inbound call arrives, RevRing sends a POST request to your webhook:

{
  "event": "pre_call",
  "agentId": "agent_456def",
  "fromNumber": "+14155551234",
  "toNumber": "+12025559999",
  "dialedAgentId": null
}

Field Descriptions:

event: Always "pre_call" for pre-call webhooks
agentId: The agent that will handle the call
fromNumber: Caller’s phone number (E.164 format)
toNumber: The number that was dialed
dialedAgentId: The agent ID when the call was routed directly to an agent (null if routed via phone number)
callback: Present only when the caller is returning a call your account placed in the callback window: { "callId", "calledAt", "outcome" } (the outbound call, when it was placed, and answered, voicemail, no_answer, busy or declined). See Callbacks

Response Format

Your webhook must respond within 5 seconds (aim for well under one: the caller is waiting in silence) with a JSON object containing variables:

{
  "variables": {
    "customer_name": "John Smith",
    "account_status": "premium",
    "last_order_date": "March 10, 2024",
    "outstanding_balance": "$0.00",
    "preferred_language": "English"
  }
}

These variables will be available in the agent’s prompt and first message using {{variable_name}} syntax.

Variables you return can override system variables like {{current_time}} and {{timezone}} if needed. However, system variables ({{direction}}, {{user_number}}, {{agent_number}}, {{current_time}}, {{timezone}}, {{language}}) are automatically provided and don’t need to be set via webhook.

Route, personalize or reject the call

The response can also decide how the call runs. Every field is optional:

{
  "variables": { "customer_name": "John Smith" },
  "agentId": "cm_spanish_support_agent",
  "environment": "staging",
  "overrides": {
    "firstMessage": "Hi John, welcome back.",
    "voiceId": "revring-maya",
    "promptAppend": "This caller has an open claim. Offer to check its status first."
  }
}

Field	Effect
`agentId`	Run the call on another agent in your organization (for example by language, region or customer tier)
`environment`	Run the agent’s version for this environment
`overrides.firstMessage`	Opening line for this call
`overrides.voiceId`	Voice for this call (an id from List Voices)
`overrides.language`	Language for this call (e.g. `es`); the agent’s language preset for it supplies the voice and opening line unless you set those too
`overrides.promptAppend`	Text added to the end of the prompt for this call
`overrides.prompt`	Replace the prompt for this call
`reject`	`true` or `{ "reason": "..." }`: the call is not answered by the agent; it is recorded as FAILED with the reason

If the agent or environment you name does not exist, the call runs on the dialed agent as usual, so a mistake in your webhook never drops a caller.

Moving from another platform? A Retell inbound webhook answer ({ "call_inbound": { "override_agent_id", "dynamic_variables" } }) and an ElevenLabs conversation initiation answer (dynamic_variables, conversation_config_override.agent.first_message and .prompt.prompt) work as they are. A Retell agent id resolves to the agent you imported from it.

Using Variables in Agent Configuration

Reference webhook variables in your First Message:

Hello {{customer_name}}, thank you for calling. I see you're a {{account_status}} member. How can I help you today?

And in your Prompt:

You are a customer service agent. You're speaking with {{customer_name}}, who is a {{account_status}} customer.

Their account information:
- Last order: {{last_order_date}}
- Balance: {{outstanding_balance}}
- Preferred language: {{preferred_language}}

Use this context to provide personalized assistance.

Error Handling

If your webhook fails, times out, or returns invalid JSON:

RevRing will proceed with the call using default variables (if configured)
The call will not be rejected - the agent will answer without personalization
Check the call’s preCallWebhookStatus field to see webhook delivery status

Webhook Status Values:

sent: Webhook responded successfully
failed: Webhook returned an error or timed out
skipped: No webhook URL configured
null: Call has not yet reached the webhook stage

Example Implementation

Node.js / Express:

app.post('/webhooks/pre-call', async (req, res) => {
  const { fromNumber, agentId } = req.body;
  
  try {
    // Look up customer in your CRM
    const customer = await crm.findByPhone(fromNumber);
    
    if (customer) {
      res.json({
        variables: {
          customer_name: customer.name,
          account_status: customer.tier,
          last_order_date: customer.lastOrderDate,
          outstanding_balance: customer.balance,
          vip: customer.isVIP ? "yes" : "no"
        }
      });
    } else {
      // Unknown caller
      res.json({
        variables: {
          customer_name: "valued customer",
          account_status: "new",
          vip: "no"
        }
      });
    }
  } catch (error) {
    console.error('Pre-call webhook error:', error);
    // Return minimal data rather than erroring
    res.json({ variables: { customer_name: "caller" } });
  }
});

Python / Flask:

@app.route('/webhooks/pre-call', methods=['POST'])
def pre_call_webhook():
    data = request.json
    from_number = data.get('fromNumber')
    
    try:
        # Look up customer
        customer = crm.find_by_phone(from_number)
        
        if customer:
            return jsonify({
                'variables': {
                    'customer_name': customer.name,
                    'account_status': customer.tier,
                    'last_order_date': customer.last_order_date,
                    'outstanding_balance': f"${customer.balance:.2f}"
                }
            })
        else:
            return jsonify({
                'variables': {
                    'customer_name': 'valued customer',
                    'account_status': 'new'
                }
            })
    except Exception as e:
        logger.error(f'Pre-call webhook error: {e}')
        return jsonify({'variables': {'customer_name': 'caller'}}), 200

Post-Call Webhooks

Post-call webhooks deliver complete call details immediately after a call ends, including the transcript, recording URL, summary, and metadata.

When to Use

Update your CRM with call outcomes
Log call details for compliance or auditing
Trigger follow-up workflows (emails, tasks, tickets)
Track agent performance metrics
Store transcripts and recordings in your system
Implement custom analytics or reporting

Configuration

Navigate to your agent’s Advanced tab

Set the Post-call Webhook URL:

https://api.yourcompany.com/webhooks/post-call

Click Save

Post-call webhooks fire for both inbound and outbound calls.

Request Format

After a call ends, RevRing sends a POST request with complete call details:

{
  "id": "a3c18021-192f-565e-87b5-5af428f29e81",
  "organizationId": "org_abc123",
  "agentId": "agent_456def",
  "agentName": "Customer Support",
  "sipTrunkId": "trunk_789ghi",
  "direction": "INBOUND",
  "status": "COMPLETED",
  "fromNumber": "+14155551234",
  "toNumber": "+12025559999",
  "agentCallerIdName": "Acme Support",
  "recordingUrl": "https://secure.revring.ai/recordings/a3c18021-192f-565e-87b5-5af428f29e81.ogg",
  "hangupCause": "END_CALL_TOOL",
  "errorMessage": null,
  "variables": {
    "customer_name": "John Smith",
    "account_status": "premium",
    "direction": "INBOUND",
    "current_time": "2:30 PM",
    "timezone": "America/New_York"
  },
  "transcript": [
    {
      "at": 0,
      "seq": 0,
      "role": "assistant",
      "text": "Hello, how can I help you today?",
      "type": "message",
      "turnId": "item_1a1f40b6737f",
      "isFinal": true
    },
    {
      "at": 4.588,
      "seq": 1,
      "role": "user",
      "text": "I have a question about my order.",
      "type": "message",
      "turnId": "user_71be2a_079a32",
      "isFinal": true,
      "language": "en-US"
    },
    {
      "at": 18.242,
      "startedAt": 16.104,
      "durationMs": 328,
      "seq": 2,
      "role": "tool",
      "tool": {
        "args": "{\"order_id\": \"ORD-12345\"}",
        "name": "check_order_status"
      },
      "type": "tool_call",
      "result": {
        "output": "{\"status\": \"shipped\", \"tracking\": \"1Z999AA10123456784\"}"
      },
      "turnId": "tool_10cde5_59dcaf"
    },
    {
      "at": 20.5,
      "seq": 3,
      "role": "assistant",
      "text": "Your order has been shipped. The tracking number is 1Z999AA10123456784.",
      "type": "message",
      "turnId": "item_2aba75c0b341",
      "isFinal": true
    },
    {
      "at": 28.5,
      "seq": 4,
      "role": "user",
      "text": "Thanks, that's all I needed.",
      "type": "message",
      "turnId": "user_728ab3_4f2a1c",
      "isFinal": true,
      "language": "en-US"
    },
    {
      "at": 30.2,
      "seq": 5,
      "role": "tool",
      "tool": {
        "args": "{}",
        "name": "end_call"
      },
      "type": "tool_call",
      "result": {
        "output": "Ending call."
      },
      "turnId": "tool_7281cd_8717e4"
    }
  ],
  "summary": "Customer inquired about their order status. Agent checked the order and confirmed it has been shipped with tracking number provided.",
  "extraction": {
    "order_number": "A1234",
    "callback_requested": false,
    "sentiment": "positive"
  },
  "evaluation": {
    "order_status_given": { "result": "pass", "rationale": "The agent confirmed the order shipped and gave the tracking number." }
  },
  "sentiment": "positive",
  "metrics": {
    "llm_prompt_tokens": 7585,
    "stt_audio_duration": 58.65,
    "tts_audio_duration": 27.14,
    "tts_characters_count": 491,
    "llm_completion_tokens": 114,
    "llm_input_audio_tokens": 0,
    "llm_output_audio_tokens": 0,
    "llm_prompt_cached_tokens": 819,
    "latency": {
      "turns": 9,
      "e2e": { "count": 9, "p50_ms": 1180, "p90_ms": 1610, "max_ms": 2240 },
      "eou_delay": { "count": 9, "p50_ms": 420, "p90_ms": 610, "max_ms": 880 },
      "transcription_delay": { "count": 9, "p50_ms": 180, "p90_ms": 260, "max_ms": 330 },
      "llm_ttft": { "count": 10, "p50_ms": 520, "p90_ms": 790, "max_ms": 1020 },
      "tts_ttfb": { "count": 10, "p50_ms": 240, "p90_ms": 300, "max_ms": 410 }
    }
  },
  "initiatedAt": "2024-03-15T14:30:00.076Z",
  "startedAt": "2024-03-15T14:30:02.529Z",
  "endedAt": "2024-03-15T14:32:00.876Z",
  "durationSeconds": 118,
  "createdAt": "2024-03-15T14:29:58.000Z",
  "updatedAt": "2024-03-15T14:32:01.000Z"
}

Key Fields:

id: Unique call identifier
organizationId: Your organization ID
agentId: The agent that handled the call
agentName: The agent’s display name
sipTrunkId: SIP trunk used for the call (null if not applicable)
direction: INBOUND or OUTBOUND
status: Final call status (COMPLETED, TRANSFERRED, FAILED, CANCELED)
fromNumber / toNumber: Caller and recipient numbers (E.164)
agentCallerIdName: Caller ID name configured on the agent (null if not set)
variables: All template variables used during the call — includes variables from pre-call webhooks, API call variables, and system variables (direction, current_time, timezone, etc.)
recordingUrl: URL to download the call recording (null if recording disabled or call not answered)
hangupCause: Reason call ended. Common values include USER_ENDED, END_CALL_TOOL, SILENCE_TIMEOUT, MAX_DURATION, VOICEMAIL_DETECTED
transcript: Complete conversation with timestamps and tool invocations (both custom tools and system tools like end_call, transfer_to_number)
summary: AI-generated summary of the call
extraction: Structured fields pulled from the transcript, as configured in the agent’s postCallExtraction (see Post-call data extraction); null when not configured
evaluation: Pass/fail/unknown verdicts for the agent’s postCallEvaluation criteria, each with a rationale (see Post-call evaluation); null when not configured
campaignId: The campaign that placed the call; null for calls not placed by a campaign
metrics: Token usage, audio durations and response latency (see Response latency)
durationSeconds: Total call duration (null if never answered)

The example above shows both a custom tool (check_order_status) and a system tool (end_call). When a call is transferred using transfer_to_number, the transcript will contain a similar tool entry with name: "transfer_to_number" and args containing to_number.

Response latency

metrics.latency shows how quickly the agent answered on this call, measured per agent turn and summarized as count, p50_ms, p90_ms and max_ms (milliseconds):

Field	Measures
`stop_to_audio`	What the caller waits: from the moment they stop talking to the agent’s first sound
`stop_to_eot`	From the moment the caller stops talking until the agent decides they have finished their turn
`e2e`	The agent’s processing time once it has decided the caller finished, to the start of its reply (the sum of the three below)
`eou_delay`	From the end of the caller’s speech until the agent decides they have finished their turn
`transcription_delay`	From the end of the caller’s speech until their words are transcribed
`llm_ttft`	From the agent starting to think to the first word of its reply
`tts_ttfb`	From the reply text to the first audio the caller hears
`turns`	Number of agent turns measured

Interrupted or discarded replies are not counted, and neither are acknowledgments the caller says while the agent is talking. Calls where the caller never spoke have count: 0. stop_to_audio and stop_to_eot are present on calls from October 10, 2026. Timing on each agent turn Agent turns in a call’s transcript carry a latency object with how long that reply took, in milliseconds. Only measured values are included.

Field	What it measures
`replyMs`	From the moment the caller stopped talking to the agent’s first sound. This is what the caller waits.
`thinkingMs`	From the end of the caller’s turn to the first words of the reply.
`voiceMs`	From the first words of the reply to the first audio of them.
`totalMs`	From the end of the caller’s turn to the first audio.

{ "type": "message", "role": "assistant", "text": "Thursday works. See you then.", "at": 63.6,
  "latency": { "replyMs": 1180, "thinkingMs": 410, "voiceMs": 95, "totalMs": 520 } }

The call page shows each reply’s time next to the turn, and the agent page shows the agent’s typical reply time over its recent calls (GET /v1/analytics/reply-times?agentId=). Tool timing fields Custom tool entries carry how long your webhook took to respond, so you can measure tool latency yourself from the transcript, with no need to ask support:

Field	Meaning
`startedAt`	Seconds from the start of the call to the moment the tool began running
`durationMs`	Milliseconds the tool took to return, measured server side. Present on both successful and failed executions
`at`	When the entry was written to the transcript. Tool entries are written once the turn finishes, so `at` can be later than `startedAt`. Use `startedAt` and `durationMs` for timing questions

The same timing is shown on each tool card in the call transcript in the dashboard.

For complete field descriptions and additional examples, see the Post-Call Webhook API Reference.

Post-call data extraction

Define the fields you want pulled out of every conversation and the platform fills them in from the transcript after each call. The result lands on the call record as extraction (GET /calls/{id}) and in the post-call webhook, so your systems get typed values instead of parsing the summary. Configure it on the agent with postCallExtraction:

PATCH /v1/agents/{id}
{
  "postCallExtraction": {
    "fields": [
      { "name": "callback_requested", "type": "boolean", "description": "Did the caller ask to be called back?" },
      { "name": "preferred_day", "type": "enum", "values": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"], "description": "Day of the week the caller prefers for the callback" },
      { "name": "budget", "type": "number", "description": "Budget the caller mentioned, in dollars" },
      { "name": "notes", "type": "string", "description": "Anything else the caller asked for" }
    ]
  }
}

Each field has:

Property	Meaning
`name`	Key in the result. Letters, digits and underscores, starting with a letter. Unique per agent
`type`	`string`, `number`, `boolean` or `enum`
`values`	The allowed values, for `enum` fields only
`description`	What to extract, written the way you would brief a person. The clearer it is, the better the result

How it behaves:

Up to 20 fields per agent. Set postCallExtraction to null to turn it off.
Values come only from what was said on the call. A field that was not stated, or was unclear, is null, never guessed.
Every configured field is present in the result, so your handler can rely on the keys.
Extraction runs after the call ends, alongside the summary, and is skipped for calls with no caller speech (unanswered dials, dead lines). Those calls carry extraction: null.
The result is included in the same post-call webhook delivery. No extra request to make.

A matching result for the config above:

"extraction": {
  "callback_requested": true,
  "preferred_day": "Tuesday",
  "budget": 450000,
  "notes": null
}

Keep descriptions specific. “The caller’s budget in dollars” extracts better than “budget”, and enum fields with a short list of values give you clean data for routing and reporting.

Post-call evaluation

Write the outcomes you care about in plain language and every call is judged against them after it ends. Each criterion comes back as pass, fail or unknown with a one-sentence rationale, on the call record as evaluation (GET /calls/{id}) and in the post-call webhook. Use it for success rates, QA sampling and routing follow-ups. Configure it on the agent with postCallEvaluation:

PATCH /v1/agents/{id}
{
  "postCallEvaluation": {
    "criteria": [
      { "name": "appointment_confirmed", "description": "The caller confirmed an appointment date and time" },
      { "name": "objection_handled", "description": "If the caller raised a concern about price, the agent addressed it before moving on" },
      { "name": "callback_requested", "description": "The caller asked to be called back" }
    ]
  }
}

How it behaves:

Up to 10 criteria per agent. Set postCallEvaluation to null to turn it off.
A criterion that asks the agent to do something is fail when the call reached that point and the agent did not do it: a skipped required action counts against the agent.
A criterion about an outcome that depends on the caller (they book, buy, pay or share information) is fail when the call got to that topic and it did not happen, and unknown when the call never got there.
unknown also covers calls that ended before the agent could respond, so your success rate reflects what actually happened rather than guesses.
Every criterion is present in the result, so your handler can rely on the keys.
Runs after the call ends, alongside the summary and extraction, and is skipped for calls with no caller speech. Those calls carry evaluation: null.
Included in the same post-call webhook delivery.

A matching result:

"evaluation": {
  "appointment_confirmed": { "result": "pass", "rationale": "The caller agreed to Tuesday at 10am and the agent confirmed it." },
  "objection_handled": { "result": "unknown", "rationale": "The caller never raised a concern about price." },
  "callback_requested": { "result": "fail", "rationale": "The caller said not to call again." }
}

Pass rates per criterion over any date range are in the analytics overview (evaluation) and on the dashboard’s Analytics page, so success rates need no spreadsheet.

State each criterion as a single observable outcome. “The caller confirmed an appointment date and time” judges cleanly; “the call went well” does not. Conditional criteria work too: “If the caller asked about pricing, the agent quoted the monthly price”.

Caller sentiment

Every call with caller speech gets a sentiment: how the caller felt over the call as a whole, positive, neutral, negative or unknown (the caller barely spoke or the call ended too soon to tell). It is on the call record (GET /calls/{id}), in the post-call webhook, and in the call-history export. Calls with no caller speech carry sentiment: null. With the Retell compatibility format, it fills call_analysis.user_sentiment (an imported user_sentiment extraction field takes precedence).

Re-run analysis on past calls

Changed an agent’s extraction fields or success criteria? Re-run extraction, evaluation and sentiment on past calls with the agent’s current settings, without placing new calls:

# One call (optionally deliver the post-call webhook again with the new results)
curl -X POST https://api.revring.ai/v1/calls/{id}/reanalyze \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "resendWebhook": false }'

# Up to 50 of an agent's calls in a time window, newest first
curl -X POST https://api.revring.ai/v1/calls/reanalyze \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "agentId": "cm...", "from": "2026-10-01T00:00:00Z", "limit": 50 }'

In the dashboard, open a call and select Re-run analysis. A field or criterion that was removed from the agent is cleared on the call. Calls still in progress, calls with no caller speech, and calls whose content was deleted under the agent’s data controls are skipped.

Export call history

GET /v1/calls/export returns a CSV of calls, newest first (up to 10,000 per file), filtered by agentId, status, direction, from and to. Columns: call details, sentiment, summary, recordingUrl, one var.* column per call variable, one extraction.* column per extracted field, and one evaluation.* column per success criterion (its result). In the dashboard, use Export CSV on Calls. Cells that would run as a spreadsheet formula are prefixed with an apostrophe.

Call started event

To also hear when a call connects, set the agent’s webhookEvents to ["call.started"]. The post-call webhook URL then receives, once per answered call:

{
  "event": "call.started",
  "call": {
    "id": "a1b2c3d4-...",
    "agentId": "cm...",
    "agentName": "Front Desk",
    "direction": "OUTBOUND",
    "fromNumber": "+14155550100",
    "toNumber": "+14155550123",
    "variables": { "first_name": "Ana" },
    "campaignId": null,
    "startedAt": "2026-10-05T22:03:56.005Z"
  }
}

The post-call payload itself has no event field, so a handler can tell the two apart. With the Retell compatibility format the event is Retell’s call_started. Started events are sent once and are not retried.

Transfer events

To hear about transfers as they happen, add any of transfer.started, transfer.bridged and transfer.cancelled to the agent’s webhookEvents (or turn on Also send transfer events in the agent’s Advanced tab). The post-call webhook URL then receives:

Event	When
`transfer.started`	The agent starts a transfer. `transfer.type` is `warm` (the agent briefs the person first) or `cold` (the caller is handed straight over).
`transfer.bridged`	A warm transfer connected: the person accepted and the caller is now talking to them.
`transfer.cancelled`	A warm transfer did not go through. `transfer.reason` is `declined`, `voicemail` or `failed`; the agent stays with the caller.

{
  "event": "transfer.started",
  "at": "2026-10-06T14:02:11.418Z",
  "call": {
    "id": "c1f3...",
    "organizationId": "cm...",
    "agentId": "cm...",
    "agentName": "Front Desk",
    "direction": "INBOUND",
    "fromNumber": "+14155550123",
    "toNumber": "+14155550100",
    "campaignId": null,
    "startedAt": "2026-10-06T14:00:52.003Z"
  },
  "transfer": { "type": "warm", "to": "+14155550199" }
}

With the Retell compatibility format the events are Retell’s transfer_started, transfer_bridged and transfer_cancelled. Transfer events are sent once and are not retried; the post-call webhook still arrives when the call ends.

Compatibility formats

Moving from another voice platform? Set the agent’s postCallWebhookFormat and the post-call webhook is sent in that platform’s payload shape, so the handler you already run keeps working while you switch. Agents created by the importer get this set for you.

`postCallWebhookFormat`	What your endpoint receives
`revring` (default)	The RevRing payload above
`retell`	Retell AI’s `call_ended` event, then `call_analyzed` with `call_analysis` (`call_summary`, `in_voicemail`, `user_sentiment`, `call_successful`, `custom_analysis_data`). Timestamps and durations in milliseconds, `transcript`, `transcript_object` and `transcript_with_tool_calls`, `disconnection_reason`
`elevenlabs`	ElevenLabs Agents’ `post_call_transcription` (`data.transcript`, `data.metadata` in seconds, `data.analysis` with `evaluation_criteria_results`, `data_collection_results`, `call_successful` and `transcript_summary`), or `call_initiation_failure` for an outbound call that never connected

The values come from the call record: extraction fields become Retell’s custom_analysis_data or ElevenLabs’ data_collection_results, evaluation criteria become call_successful (and ElevenLabs’ evaluation_criteria_results), and an extraction field named user_sentiment fills Retell’s user_sentiment. Fields that only exist on the other platform, such as costs or per-word timings, are not sent. Deliveries are signed with RevRing’s X-RevRing-Signature header, not the other platform’s signature, so replace your signature check (see Verify webhook sources). Retries work as described below.

Response Expectations

Your webhook should:

Respond with 200 OK status code
Respond within 30 seconds (a few seconds is better: acknowledge first, then process)
Handle the webhook asynchronously if processing takes time

RevRing does not require any specific response body. Simply acknowledge receipt:

{ "received": true }

Retries: a delivery that fails (connection error, timeout, or any non-2xx response) is retried three times, 1 minute, 5 minutes and 30 minutes later. Make your handler idempotent on the call id: a retry carries the same payload, and a slow handler that returned after our 30 second timeout may be retried even though it processed the call. The call record shows the outcome in postCallWebhookStatus (sent, retrying, failed) with postCallWebhookAttempts.

Error Handling

If your webhook fails (non-2xx status), can’t be reached, or times out:

The delivery is retried automatically 1, 5 and 30 minutes later (see Retries above); postCallWebhookStatus is retrying meanwhile
After the last retry it is marked failed in the call record
To backfill anything that ended failed (for example after a long outage on your side), list recent calls with GET /calls and check postCallWebhookStatus

Webhook Status Values:

sent: Delivered successfully
failed: Webhook returned an error or timed out
skipped: No webhook URL configured
null: Call has not yet reached the webhook stage

Example Implementation

Node.js / Express:

app.post('/webhooks/post-call', async (req, res) => {
  const call = req.body;
  
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  try {
    // Update CRM with call details
    await crm.logCall({
      callId: call.id,
      phone: call.fromNumber,
      duration: call.durationSeconds,
      summary: call.summary,
      recording: call.recordingUrl,
      timestamp: call.endedAt
    });
    
    // Create follow-up task if needed
    if (call.summary.includes('callback')) {
      await tasks.create({
        title: `Follow up from call`,
        dueDate: tomorrow(),
        notes: call.summary
      });
    }
    
    // Store transcript for compliance
    await db.transcripts.insert({
      callId: call.id,
      transcript: call.transcript,
      recordingUrl: call.recordingUrl
    });
    
    console.log(`Processed call ${call.id}`);
  } catch (error) {
    console.error('Post-call processing error:', error);
    // Don't throw - webhook already acknowledged
  }
});

Python / Flask:

@app.route('/webhooks/post-call', methods=['POST'])
def post_call_webhook():
    call = request.json
    
    # Acknowledge immediately
    response = jsonify({'received': True})
    
    # Process in background
    Thread(target=process_call, args=(call,)).start()
    
    return response, 200

def process_call(call):
    try:
        # Update CRM
        crm.log_call(
            call_id=call['id'],
            phone=call['fromNumber'],
            duration=call['durationSeconds'],
            summary=call['summary'],
            recording=call['recordingUrl']
        )
        
        # Check for action items in summary
        if 'refund' in call['summary'].lower():
            tickets.create(
                title=f"Refund request from call",
                priority='high',
                description=call['summary']
            )
        
        logger.info(f"Processed call {call['id']}")
    except Exception as e:
        logger.error(f"Post-call processing error: {e}")

Security Best Practices

Verify Webhook Sources

Signature verification (recommended): Turn on webhook signing for your organization and verify every request. One secret signs every webhook RevRing sends you: pre-call, post-call and message received.

Create a secret (the full value is returned only by this call; store it with your other secrets):

curl -X POST https://api.revring.ai/v1/webhooks/signing-secret -H "x-api-key: $REVRING_API_KEY"
# { "data": { "secret": "whsec_...", "enabled": true, "last4": "a1b2" } }

From then on each webhook carries two headers:

Header	Value
`X-RevRing-Timestamp`	Unix time in seconds when the request was signed
`X-RevRing-Signature`	`v1=` followed by hex HMAC-SHA256 of `"{timestamp}.{raw body}"` using your secret

Verify on the raw request body, before parsing JSON, and reject timestamps older than a few minutes:

import crypto from "node:crypto";

function verifyRevRingSignature(rawBody, headers, secret, toleranceSeconds = 300) {
  const timestamp = Number(headers["x-revring-timestamp"]);
  const signature = headers["x-revring-signature"] || "";
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

// Express: keep the raw body for verification
app.post("/webhooks/post-call", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyRevRingSignature(req.body.toString("utf8"), req.headers, process.env.REVRING_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const call = JSON.parse(req.body.toString("utf8"));
  // ...
  res.status(200).end();
});

import hmac, hashlib, time

def verify_revring_signature(raw_body: bytes, headers, secret: str, tolerance_seconds: int = 300) -> bool:
    try:
        timestamp = int(headers.get("X-RevRing-Timestamp", ""))
    except ValueError:
        return False
    if abs(time.time() - timestamp) > tolerance_seconds:
        return False
    expected = "v1=" + hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-RevRing-Signature", ""))

Rotate with the same POST (the new secret is live within a minute; verify against both during the switch), check the state with GET, and turn signing off with DELETE. See the signing secret reference. Request Validation: Implement validation to ensure webhook requests contain expected fields and structure.

Use HTTPS

Always use HTTPS for webhook URLs to ensure data is encrypted in transit:

✓ https://api.yourcompany.com/webhooks/pre-call
✗ http://api.yourcompany.com/webhooks/pre-call

Validate Payload

Validate incoming webhook data before processing:

app.post('/webhooks/post-call', (req, res) => {
  const call = req.body;
  
  // Validate required fields
  if (!call.id || !call.status || !call.direction) {
    return res.status(400).json({ error: 'Invalid payload' });
  }
  
  // Validate id format (UUID)
  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(call.id)) {
    return res.status(400).json({ error: 'Invalid call id' });
  }
  
  // Process...
});

Rate Limiting

Implement rate limiting to prevent abuse:

const rateLimit = require('express-rate-limit');

const webhookLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minute
  max: 100 // max 100 requests per minute
});

app.post('/webhooks/post-call', webhookLimiter, (req, res) => {
  // Process webhook
});

Testing Webhooks

Local Development with ngrok

For local testing, use ngrok to expose your local server:

# Start your local server on port 3000
npm start

# In another terminal, start ngrok
ngrok http 3000

Use the ngrok HTTPS URL in your webhook configuration:

https://abc123.ngrok.io/webhooks/pre-call

Testing Tools

Request Inspection: Use webhook.site to inspect webhook payloads without writing code. Manual Testing: Use curl to simulate webhook responses:

curl -X POST http://localhost:3000/webhooks/pre-call \
  -H "Content-Type: application/json" \
  -d '{
    "event": "pre_call",
    "agentId": "cmhckjdxw0001ik0hj4jnn49f",
    "fromNumber": "+14155551234",
    "toNumber": "+12025559999"
  }'

Test with Real Calls

Configure your webhook URL in the Advanced tab
For pre-call webhooks: use the test panel to make a browser call and check your server logs
For post-call webhooks: use either the test panel or the Make a Call page
Check call details in Calls to verify webhook status

Monitoring Webhooks

Check Webhook Status

For each call in Calls:

Click on the call to view details
Check Webhook Status in the Overview card:
- Pre-call webhook status
- Post-call webhook status
If failed, review your server logs for errors

Common Issues

Webhook returns timeout

Ensure your webhook responds within 5 seconds (pre-call; the caller is waiting) or 30 seconds (post-call)
Move slow operations (database writes, external API calls) to async background processing
Return acknowledgment immediately, then process in background
Check your server’s response time and optimize slow queries

Webhook marked as failed

Verify your endpoint is accessible from the internet
Check that you’re returning a 200 status code
Ensure response is valid JSON (even if empty: {})
Review server logs for exceptions or errors
Test endpoint with curl or Postman to verify it works

Variables not appearing in agent responses

Verify your pre-call webhook returns valid JSON with variable keys
Check variable names match exactly between webhook and prompt (case-sensitive)
Ensure the webhook responds within 5 seconds; after that the call starts without its variables
Test webhook independently to confirm it returns expected data
Review the call’s variables field in call logs to see what was actually received

Not receiving post-call webhooks

Confirm the webhook URL is configured in the agent’s Advanced tab
Verify the URL is correct and accessible
Check your server logs - RevRing may be sending but your server isn’t logging
Test with webhook.site to confirm RevRing is sending requests
Review firewall rules that might block incoming requests

Best Practices

Performance

Respond quickly: Acknowledge webhooks within 1-2 seconds
Process asynchronously: Handle heavy processing in background jobs
Cache frequently: Cache CRM lookups or database queries when possible
Use connection pooling: Reuse database connections across requests
Set timeouts: Configure timeouts for external API calls to prevent hanging

Reliability

Idempotency: Design webhooks to handle duplicate calls (use id as idempotency key)
Error handling: Wrap processing in try/catch and return 200 even if internal processing fails
Logging: Log all webhook requests and responses for debugging
Monitoring: Set up alerts for webhook failures or high error rates
Fallbacks: Provide default values if lookups fail

Security

HTTPS only: Never use HTTP for webhook URLs
Validate input: Sanitize and validate all incoming data
Request validation: Verify requests contain expected structure and fields
Rate limiting: Protect against potential abuse
Audit logging: Log all webhook activity for security review

Advanced Patterns

Dynamic Agent Customization

Use pre-call webhooks to provide variables that customize agent behavior for each caller: Webhook Response:

{
  "variables": {
    "firstName": "John",
    "accountType": "premium",
    "lastPurchase": "March 15, 2024",
    "supportHours": "Monday-Friday 9am-5pm EST"
  }
}

Reference in First Message:

Hi {{firstName}}, thanks for calling! How can I help you today?

Reference in Prompt:

You are a customer service agent speaking with {{firstName}}, who is a {{accountType}} customer.
Their last purchase was on {{lastPurchase}}.

If asked about business hours, say: {{supportHours}}

Call Outcome Tracking

Use post-call webhooks to track outcomes and trigger workflows:

app.post('/webhooks/post-call', async (req, res) => {
  const { summary, id, durationSeconds } = req.body;
  
  res.json({ received: true });
  
  // Categorize call outcome
  let outcome = 'unknown';
  if (summary.includes('appointment scheduled')) outcome = 'scheduled';
  if (summary.includes('transferred')) outcome = 'escalated';
  if (summary.includes('resolved')) outcome = 'resolved';
  
  // Update analytics
  await analytics.track({
    event: 'call_completed',
    callId: id,
    outcome: outcome,
    duration: durationSeconds
  });
  
  // Trigger workflows
  if (outcome === 'scheduled') {
    await calendar.sendConfirmation(id);
  }
});

Inbound Message Webhook

When an agent’s inbound messaging mode is set to notify, RevRing forwards each incoming text to a webhook URL you choose, and your own system composes and sends the reply. (In auto-reply mode RevRing replies automatically from the agent’s SMS prompt, and no webhook is sent — see Two-way texting.)

When to Use

You orchestrate replies yourself (in N8N, Make, your CRM, etc.) and want full control over each reply.
You want to log, score, or branch on an inbound text before responding.

Configuration

On the agent’s Messaging tab, set When a text comes in to Notify my webhook and enter your webhook URL.
Assign the receiving number to the agent under Numbers.
Point your provider’s inbound message webhook at RevRing:

https://api.revring.ai/webhooks/twilio/inbound

Request Format

When an inbound text arrives, RevRing sends a POST request to your webhook URL:

{
  "event": "message_received",
  "organizationId": "org_123abc",
  "agentId": "agent_456def",
  "conversationId": "conv_789ghi",
  "fromNumber": "+14155551234",
  "toNumber": "+12025559999",
  "body": "Yes, that time works for me",
  "messageSid": "SM0123456789abcdef"
}

Field Descriptions:

event: Always "message_received" for inbound messages.
organizationId: Your organization ID.
agentId: The agent that owns the number that received the text.
conversationId: RevRing’s id for the thread with this contact. Use it with the messages log to read the full conversation.
fromNumber: The contact’s number (E.164).
toNumber: Your number that received the text (E.164).
body: The text content of the incoming message.
messageSid: Your provider’s id for the inbound message.

Response Expectations

Respond with 200 OK promptly. RevRing does not require a response body and does not retry. To reply, call the Send Message API.

Example Implementation

Node.js / Express:

app.post('/webhooks/revring-inbound', async (req, res) => {
  const { fromNumber, toNumber, agentId } = req.body

  // Acknowledge immediately
  res.status(200).json({ received: true })

  // Reply via RevRing. Pass your own `body`, or let RevRing write it from the
  // agent's SMS prompt with `generate: true`. Set `from` to the number that
  // received the text so the reply continues the same conversation.
  await fetch('https://api.revring.ai/v1/messages', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.REVRING_API_KEY,
      'content-type': 'application/json',
    },
    body: JSON.stringify({ agentId, to: fromNumber, from: toNumber, generate: true }),
  })
})

Python / Flask:

@app.route('/webhooks/revring-inbound', methods=['POST'])
def revring_inbound():
    data = request.get_json()
    requests.post(
        'https://api.revring.ai/v1/messages',
        headers={'x-api-key': os.environ['REVRING_API_KEY']},
        json={
            'agentId': data['agentId'],
            'to': data['fromNumber'],
            'from': data['toNumber'],
            'generate': True,
        },
    )
    return {'received': True}, 200

Next Steps

Tools

Configure system and custom tools

API Reference

View complete webhook API documentation

Inbound Calls

Set up inbound call handling

Outbound Calls

Configure outbound calling

​Webhook Types

​Pre-Call Webhooks

​When to Use

​Configuration

​Request Format

​Response Format

​Route, personalize or reject the call

​Using Variables in Agent Configuration

​Error Handling

​Example Implementation

​Post-Call Webhooks

​When to Use

​Configuration

​Request Format

​Response latency

​Post-call data extraction

​Post-call evaluation

​Caller sentiment

​Re-run analysis on past calls

​Export call history

​Call started event

​Transfer events

​Compatibility formats

​Response Expectations

​Error Handling

​Example Implementation

​Security Best Practices

​Verify Webhook Sources

​Use HTTPS

​Validate Payload

​Rate Limiting

​Testing Webhooks

​Local Development with ngrok

​Testing Tools

​Test with Real Calls

​Monitoring Webhooks

​Check Webhook Status

​Common Issues

​Best Practices

​Performance

​Reliability

​Security

​Advanced Patterns

​Dynamic Agent Customization

​Call Outcome Tracking

​Inbound Message Webhook

​When to Use

​Configuration

​Request Format

​Response Expectations

​Example Implementation

​Next Steps

Tools

API Reference

Inbound Calls

Outbound Calls

Webhook Types

Pre-Call Webhooks

When to Use

Configuration

Request Format

Response Format

Route, personalize or reject the call

Using Variables in Agent Configuration

Error Handling

Example Implementation

Post-Call Webhooks

When to Use

Configuration

Request Format

Response latency

Post-call data extraction

Post-call evaluation

Caller sentiment

Re-run analysis on past calls

Export call history

Call started event

Transfer events

Compatibility formats

Response Expectations

Error Handling

Example Implementation

Security Best Practices

Verify Webhook Sources

Use HTTPS

Validate Payload

Rate Limiting

Testing Webhooks

Local Development with ngrok

Testing Tools

Test with Real Calls

Monitoring Webhooks

Check Webhook Status

Common Issues

Best Practices

Performance

Reliability

Security

Advanced Patterns

Dynamic Agent Customization

Call Outcome Tracking

Inbound Message Webhook

When to Use

Configuration

Request Format

Response Expectations

Example Implementation

Next Steps