Skip to main content

Webhook App - Universal API Integration

Premium

Overview​

The Webhook app enables integration between Call Telemetry and external REST APIs. Use this app for real-time CRM lookups during call setup, post-call analytics, notifications to collaboration platforms, and other REST API integrations.

Why Use the Webhook App​

  • Universal Integration: Connect to any REST API - CRM, ticketing, analytics, notifications
  • Real-time Processing: Enrich calls with external data before they connect
  • Post-call Analytics: Send realtime call data to analytics platforms
  • Template Variables: Use any call or app data in your requests

Key Features​

  • HTTP Methods: GET, POST
  • Authentication: None, Basic, Bearer Token, OAuth 2.0
  • Custom Headers: Add any HTTP headers your API requires
  • Dynamic URLs: Template variables in URLs for RESTful endpoints
  • JSON Support: Send and receive JSON payloads with full template support
  • Error Handling: Configurable timeouts and retry logic

Prerequisites​

Before configuring the Webhook app:

For XML/SOAP support, use the XML SOAP Query App

Configuration Steps​

Step 1: Create the Webhook App​

Navigate to Policies → Apps → Select app type:

  • Real-time - For caller ID lookups and call enrichment during call setup
  • Post Call - For analytics and notifications after call completion

Learn more about Real-time vs Post-call Apps.

Select Webhook → Click Create App

Step 2: Configure Basic Settings​

Fill in the basic webhook details:

  • App Name - "Salesforce CRM Lookup" or "Slack Notifications"
  • Description - Brief description of what this webhook does
  • App Order - Execution order (10-100) - controls when this app runs relative to other apps. See Call Apps Execution Order for details
  • URL - Your API endpoint (supports template variables)
  • Method - GET or POST
URL Templates

You can also use template variables in URLs.

https://api.company.com/contacts/{{ event.calling_number }}/details

Step 3: Set Up Authentication (optional)​

Choose your authentication method:

No Authentication​

Default option for public APIs or internal services

Bearer Token​

For modern APIs using token authentication:

  • Select Bearer as auth type
  • Enter your API token in the Bearer Token field

Basic Authentication​

For legacy systems or simple auth:

  • Select Basic as auth type
  • Enter Username and Password

OAuth 2.0 (Client Credentials Flow)​

For enterprise APIs using OAuth:

  • Select OAuth2 as auth type
  • Enter Token URL - The OAuth token endpoint
  • Enter Client ID - Your OAuth application's client ID
  • Enter Client Secret - Your OAuth application's client secret
  • Enter Scope (optional) - OAuth scope for requesting specific permissions
  • Grant type is automatically set to client_credentials

Step 4: Configure Headers (optional)​

Add any custom headers your API requires:

  • Click Add Header
  • Enter header name and value
Default Headers

The webhook app automatically includes Content-Type: application/json for all requests.

Step 5: Build Your Request​

Optional Query Parameters for GET requests​

Add query parameters:

  • Click Add Parameter
  • Enter parameter name
  • Enter value (supports templates like {{ event.calling_number }})

Body for POST Requests​

Create your JSON body using template variables:

{
  "phone": "{{ event.calling_number }}",
  "called": "{{ event.called_number }}",
  "timestamp": "{{ event.timestamp }}",
  "device": "{{ event.calling_devicename }}"
}

Step 6: Configure Reliability Settings (Optional)​

  • Timeout - Default: 30s (use 5s or less for real-time apps)
  • Retry Count - Default: 3 (only retries on 5xx/network errors)
  • Retry Delay - Default: 1s (doubles with each retry)

Available Template Variables​

Call Event Data​

  • {{ event.calling_number }} - Calling party number
  • {{ event.called_number }} - Called party number
  • {{ event.calling_name }} - Calling party name
  • {{ event.calling_devicename }} - Device name (e.g., SEP123456789ABC)
  • {{ event.trigger_point_type }} - Where call was intercepted

Phone Discovery Data (if Phone Discovery app runs first)​

  • {{ app_data.phone-discovery.data.phone.ip }} - Phone IP address
  • {{ app_data.phone-discovery.data.phone.extension }} - Extension
  • {{ app_data.phone-discovery.data.phone.model }} - Phone model
  • {{ app_data.phone-discovery.data.phone.device_name }} - SEP MAC address
  • {{ app_data.phone-discovery.data.phone.description }} - Phone description
  • {{ app_data.phone-discovery.data.neighbor.neighbor_name }} - Connected switch
  • {{ app_data.phone-discovery.data.neighbor.neighbor_port }} - Switch port
  • {{ app_data.phone-discovery.data.subnet }} - Phone subnet

Data from Other Apps​

  • {{ app_data.[app-name].data.field }} - Access any field from previous apps
  • {{ app_data.[app-name].message }} - Formatted message from previous apps

Understanding Webhook Responses​

The webhook app stores the entire JSON response under the data key, making it available to subsequent apps.

Example: CRM API Response​

If your CRM API returns:

{
  "customer_id": "CUST-12345",
  "name": "John Doe",
  "company": "ACME Corp",
  "vip": true,
  "support_tier": "Gold"
}

This data is available as:

  • {{ app_data.webhook.data.customer_id }} → "CUST-12345"
  • {{ app_data.webhook.data.name }} → "John Doe"
  • {{ app_data.webhook.data.vip }} → true

Common Integration Use Cases​

Customer Data Lookup​

Look up caller information from your CRM or database to provide agents with context before answering. Display customer history, account status, or recent interactions.

Real-time Notifications​

Send alerts to collaboration platforms when specific calls occur - VIP customers, emergency calls, or after-hours contacts. Keep teams informed without constant monitoring.

Call Logging & Analytics​

Automatically create tickets, log call details, or send metrics to your analytics platform. Track call patterns, measure response times, and identify trends.

Workflow Automation​

Trigger business processes based on call events - update lead status, create follow-up tasks, or initiate approval workflows. Connect calls to your existing business systems.

For a detailed example see CRM Integration with Webhooks.

Testing and Troubleshooting Your Webhook App​

Using Call Test​

  1. Go to Policies → Call Test
  2. Enter test calling and called numbers
  3. Select the policy with your webhook app
  4. Click Run Test
  5. Check Results:
    • Look for your webhook app in the right side raw JSON results
    • Verify the data section contains expected response
    • Check for any error messages

Template Variable Issues​

If variables aren't being replaced:

  • Check variable names are spelled correctly
  • Ensure the data path exists (e.g., Phone Discovery App must run first)
  • Ensure the app slug matches your app name (e.g., app_data.webhook if your app is named "webhook")
  • Use exact syntax: {{ variable }} with spaces

App Stacking Order​

The order in which apps execute is critical for data dependencies:

  1. Phone Discovery (Order: 10-20) - Gathers phone network details
  2. Webhook CRM Lookup (Order: 30-50) - Uses phone data for lookups
  3. Alert Apps (Order: 80-100) - Uses enriched data from previous apps

Retry Behavior​

The webhook app automatically retries failed requests (5xx errors and network issues only). Client errors (4xx) are not retried. Each retry waits progressively longer using exponential backoff.

Advanced Features​

Dynamic URLs​

Use template variables in URLs for RESTful endpoints:

https://api.company.com/contacts/{{ event.calling_number }}/details

Conditional Headers​

While you can't make headers conditional, you can use empty values:

{
  "key": "X-Custom-Header",
  "value": "{{ app_data.previous-app.data.custom_value }}"
}

URL Encoding​

Query parameters are automatically URL encoded. For example:

  • Input: +1 (555) 123-4567
  • Encoded: %2B1%20%28555%29%20123-4567

See Also​

Last updated on by Call Telemetry