Webhooks API Integration

Nicole Morrison

May 05, 2022 14:52

Webhooks 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. Webhooks are available on Marketing Pro, Sales Engage, Enterprise, Performance, Growth, and Connect plans.

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.

Note: If you use API in your account, we recommend setting up a Trigger and using the Webhook action of "Through a trigger (route)" instead of just the Webhook.

There are many use cases for setting up Webhooks.

To send an activity from CTM into a CRM application
Posting/mapping form information into or out of CTM
Used for third-party reporting tools for Dashboard updates
Scheduling applications
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 available at varying 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 complete list of trigger “phases” that are available.

Inbound call: When an Activity is 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 (third-party application URL).

Some third-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).
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

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 third-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, and Total Time. Another way to add even more custom filtering is by using a trigger to conditionally run the Webhook.
Authentication z- This feature allows optional headers for basic HTTP authentication (API Keys from your third-party application). It is an optional feature if no authentication is required to communicate with your third-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 third-party source to get data into CTM:

CTM has some capabilities for accepting an inbound webhook from a third-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 the account number as “custom_account_number”. Most third-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 third-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.

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.