Webhooks API Integration

Webhooks are used to allow web applications to communicate with one another. When an event occurs in CTM or if an event occurs in a customer's application (bidirectional) the Webhook can trigger the event to send the data in near real-time to the other application. The data is typically exchanged between applications using JSON files. 

CTM Webhooks Integration allows you to post activity data to a callback URL. You can configure activity-based triggers that will initiate a payload of data to be sent from CTM to a web address only after certain actions are performed or criteria are achieved. Testing a Webhook will trigger a request for the most recent activity in the activity log. You may find a service like https://putsreq.com/ helpful when testing your code. You can also check the API logs for debugging information for specific activities. A successful Webhook will usually return a 200 response. A failed Webhook will usually return a 400 or 500 response.  

There are many use cases for setting up Webhooks. 

1. To send an activity from CTM into a CRM application
2. Posting/mapping form information into or out of CTM
3. Used for 3rd party reporting tools for Dashboard updates
4. Scheduling applications
5. Marketing automation solutions 

To set up a Webhook Integration

Go to → Settings → Integrations → Webhooks 

Next Add:

• Name
• Description (Optional) 
• Select a Trigger 

Trigger (Action) Details:

Trigger actions determine when the actual firing of the webhook should take place. We have different information that is available at different points of the call. For example: at the start of an activity we have very little info other than the caller's number, the number they dialed, and the source associated with that number, at the end of the activity we will have the overall duration, a link to the recording, which agent answered the call, and later we will also have transcriptions, PPC data after our Google integration has run, or any post-call scoring an agent may have applied. You can also run the Webhook through another trigger (custom workflow) or an IVR menu. Below is the full list of trigger “phases” available.  

• Inbound call: When an Activity received (starts) 
• Outbound call: When an activity is sent (starts)
• Outbound call: When an agent answers a call within a call queue (answered)
• Website Session: When a website session is associated with the activity record (session)
• Hang-ups: When the caller hangs up the call early (hangup)
• Update: Multiple times throughout the call (update)
• Manual Update: Trigger when a call is manually updated (manual_update)
• Ends Immediately: Trigger when a call ends immediately without delays (end_immedite) 
• At the end of a call/forms/chat once all data has been captured (End)
• 1 hour after call data has been captured for Google Analytics (End_Delayed)
• Whenever sales data is updated for any activity (sale) 
• When a FormReactor activity is created (form)
• When PPC data is retrieved for an activity (paid)
• When cost data is retrieved for an activity (cost)
• When a caller inputs their zip code or area code for a GeoRouter (Geokey)
• After a text message has been received (inbound_text)
• After a text message has been sent (outbound_text)
• When a keyword is spotted within a call transcript (keyword)
• Through a trigger (route)
• When a text message changes status (status_change)

Choose the trigger you want to automatically run based on the activity. Select → Save 

Next, add the connection detail URL for the callback. Note: This should be a fully qualified URL and you should use a unique URL for each webhook (3rd party application URL).   

Some 3rd party web applications can process data that is passed as a URL parameter. CTM provides activity tokens that you can use to dynamically populate these URL parameters with every Webhook. For example you might build a callback URL https://yourcrm.com/?activity_id={{id}}&contact_name={{name}}&contact_number={{caller_number}} that automatically created a new record because CTM passed the name number and CTM activity ID in callback URL parameters. Any custom fields that are added to your CTM activity log will be available as tokens. 

• Activity
• Contact
• Score
• Enhanced (Requires Enhanced Caller ID) additional charges apply  

Determine the body type

• Log data - receive a POST request including all the activity log data (The most common method includes the raw JSON file with all of the data we knew about the activity at the time the webhook was sent) Example here ​​https://postman.calltrackingmetrics.com/?version=latest#aadcd6b8-f62e-7976-ebd1-9a283c4817fd 
• Resource link - receive a POST request with a link to the activity data resource
  • {"resource_url":"https://..../api/v1/accounts/{account_id}/calls/{logid}.json"}
• Pixel - receive a POST or GET request to track a pixel 
• Pixel requests - support replacement variables that allow you to customize values passed in the callback URL.
• Pixel replacement variables -are defined by (variablename) and will be replaced with data from the call record.  
• :callid - internal call ID (SMS, Chats, Forms also assigned a CTM “callid”)
• :duration - duration in seconds
• :direction - type (inbound/outbound)
• :source - tracking source name
• :sale_value - sale value

1. HTTP Request Method 
   1. POST
   2. GET - Only pixels can send GET request

Integration Format (Optional) 

• Time-based formats represent the last 7 days.
• Custom Mustache format - provides the activity as context giving full control over the request body. The custom mustache format will allow you to format the data we send however you’d like. Some 3rd party web applications can ingest the data but they don't like the raw JSON format or the resource link. The custom mustache allows you total control over how the body of data will be sent from CTM.
• Filter - conditionally trigger this webhook based on some basic rules like Tracking Source, Tracking Number, Tag, Talk Time, Total Time. Another way to add even more custom filtering is by using a trigger to conditionally run the Webhook.  
• Authentication - which allows optional headers for basic HTTP authentication (API Keys from your 3rd party application) this is an optional feature if no authentication is required to communicate with your 3rd party application.
• Failure Retries - retry sending the webhook when a failure is detected. Select a trigger that runs when the webhook fails (failure is defined as the webhook receiving a response with an HTTP Status Code of 4xx or 5xx.) For example, you might have a trigger that sends a text or email to your IT team letting them know the webhook is failing. It may be possible to manually rerun the webhook on any activities that have failed.

Using Webhooks from 3rd party source to get data into CTM: 

CTM has some capabilities for accepting an inbound webhook from a 3rd party source. The challenge is that to post to our API, data has to be formatted in a specific way so that parameters will line up. For example; we’re looking for a caller’s number to be formatted as “caller_number” tracking source as “source” or a custom field for account number as “custom_account_number”.  Most 3rd party applications have their type of format for data and don’t provide a tool for mapping what they might call “primary_phone” to our accepted format “caller_number”. 

For the 3rd party tools that provide mapping or customize the body format, the CTM API documentation is a great place to see the example formats and the required parameters for sending POST requests to CTM. A popular example would be posting data to CTM as a form shown here https://postman.calltrackingmetrics.com/?version=latest#36bf39a3-3ee5-3adc-44e0-029838d2e408 

Since most apps don’t support this custom formatting/mapping, a middleware application like Zapier or Integromat is often required to get a webhook into CTM. Zapier allows you to build the mapping and parse data from one application and put it in a specific format that works for the other application. We have a great support article for using Zapier this way here.