Webhooks

Webhooks (formerly Server Callback) are a feature intended for software developers. When activated, it sends a HTTP POST request to a URL of your choice immediately after each call is completed. This URL can be configured on a per-company basis.  The request will contain data in the JSON format.

Use this article to learn:

  • How to add webhooks to a company in your account
  • Parameters and requests you can use
  • How to test your webhooks

Getting Started

Webhooks allow you to send real-time call notifications to your own web applications and reporting systems. There are three types of webhooks for calls, pre-call, post-call, and call modified webhooks.  

  • Pre-Call Webhook: The pre-call webhook executes the moment the phone call is received by CallRail. Your server will receive the call information before the call is connected, allowing you to develop real-time systems for your representatives, such as screen-pops or CRM database lookups.

    Because the pre-call webhook executes before the call is connected, it contains less information than the post-call webhook. For example, the post-call webhook will contain the call duration, whether the call was answered, and a link to the recording (if applicable).

  • Post-Call Webhook: The post-call webhook executes immediately after the phone call has completed. It contains the full data about the call, as described below.

  • Call Modified Webhook: The call modified webhook is sent when a call has changed after it has ended. For example, adding a tag or note, or when a delayed call recording has come available.

  • Query String Data Deprecated: All attributes are available in the JSON POST body, and this is what we recommend using. A limited number of attributes are available in the query string. New attributes are only being added to the JSON POST body.

Example Request

  POST "/?datetime=2012-08-22+20%3A44%3A43&trackingnum=%2B14047773734&callernum=%2B17451187568&destinationnum=4041234567&callsource=disabled&callername=Olivia+Rodriguez&keywords=&referrer=&referrermedium=&landingpage=&recording=https%3A%2F%app.callrail.com%2Fcalls%2F197479887%2Frecording%2Fc9ad534a44ee2b426c4e&answered=true&duration=291&first_call=true"

JSON Body:
{
  "datetime": "2013-02-05 16:14:43",
  "trackingnum": "+14047773734",
  "callernum": "+17451187568",
  "destinationnum": "4041234567",
  "callsource": "disabled",
  "callername": "Olivia Rodriguez",
  "keywords": "",
  "referrer": "",
  "referrermedium": "",
  "landingpage": "",
  "recording": "https://app.callrail.com/calls/247716205/recording/1b6d7d5f0c54f2e2ed4b",
  "answered": true,
  "duration": "157",
  "first_call": true
}

Pre-Call, Post-Call Webhook, & Call Modified Parameters

  • id
    • The call's ID, which can be used to retrieve the call from our API.
    • Example: 123456789
  • callsource
    • The marketing source responsible for the call.
    • Example: www.facebook.com.
  • datetime
    • The start time of the call in UTC.
    • Example: 2011-01-01 01:01:01
  • trackingnum
    • The tracking phone number that was dialed in E.164 format.
    • Example: +17703334444
  • customer_phone_number
    • The caller’s number in E.164 format.
    • Example: +17703334444
  • destinationnum
    • The destination number in E.164 format.
    • Example: +17703334444
  • customer_name
    • The caller's name as it appears on caller ID.
  • customer_city
    • The caller's city.
  • customer_state
    • The caller's state.
  • customer_zip
    • The caller's zip code.
  • customer_country
    • The caller's country.
  • keywords
    • The keyword phrase associated with the call.
  • referrer
    • The full referrer URL associated with this call.
  • referrermedium
    • The referrer medium, either PPC or Organic.
  • landingpage
    • The full URL of the landing page.
  • last_requested_url
    • The full URL of the active page at the time the call was placed.
  • gclid
    • The call's gclid as captured from Google AdWords.
  • ip
    • The caller's most recent IP address as captured from their web session.
  • utm_source
    • The call's utm_source as captured from the landing page parameter.
  • utm_medium
    • The call's utm_medium as captured from the landing page parameter.
  • utm_term
    • The call's utm_term as captured from the landing page parameter.
  • utm_content
    • The call's utm_content as captured from the landing page parameter.
  • utm_campaign
    • The call's utm_campaign as captured from the landing page parameter.
  • utma
    • Google Analytics _utma value.
  • utmb
    • Google Analytics _utmb value.
  • utmc
    • Google Analytics _utmc value.
  • utmv
    • Google Analytics _utmv value.
  • utmz
    • Google Analytics _utmz value.
  • utmx
    • Google Analytics _utmx value.
  • ga
    • Google Analytics _ga value, used for Universal Analytics.
  • first_call
    • Boolean that indicates if this the first call the company has ever received from this phone number.
    • Example: true
  • callernum
    • DEPRECATED See customer_phone_number.
  • callername
    • DEPRECATED See customer_name.
  • callercity
    • DEPRECATED See customer_city.
  • callerstate
    • DEPRECATED See customer_state.
  • callerzip
    • DEPRECATED See customer_zip.
  • callercountry
    • DEPRECATED See customer_country.

Post-Call & Call Modified Webhook Parameters

  • duration
    • The duration of the call in seconds.
  • recording
    • The URL for the call recording, if available.
  • answered
    • Whether or not the call was answered, sent as a boolean.
  • note
    • A free-form text note associated with the call.
  • tag
    • The call's tag, if set.
    • Example: "New Lead"
  • call transcription
    • The conversational transcript of the call, if you're using CallScribe.
  • spotted keyword(s)
    • Any keyword spotted during a call if you're using Keyword Spotting. We'll parse out the speaker, and time the keyword was spoken during the call. 
  • speaker percentage
    • The percentage of time on a call that agent and customer spent talking if you have call recording enabled.
    • Example: 
      speaker_percent: {
         agent: 20
         customer: 80
      }

Call Modified Webhook Parameters

  • changes
    • The changes to the call that triggered the call modified webhook.
    • Example: ["tag", "note", "recording"]

Text Message Received Webhook Parameters

  • agency id
    • The CallRail account number assigned to the agency
    • Example: 111222333
  • source number
    • The tracking phone number that received the message, in E.164 format
    • Example: +17703334444
  • destination number
    • The destination number, in E.164 format
    • Example: +17703334444
  • message content
    • The message received by the tracking number
  • sent time
    • The timestamp for when the message was received by the tracking number

Text Message Sent Webhook Parameters

  • agency id
    • The CallRail account number assigned to the agency
    • Example: 111222333
  • source number
    • The tracking phone number that sent the message, in E.164 format
    • Example: +17703334444
  • destination number
    • The destination number, in E.164 format
    • Example: +17703334444
  • message content
    • The message sent by the tracking number
  • received time
    • The timestamp for when the message was sent by the tracking number

Adding a Webhook to CallRail

  1. Choose the company where you'd like to add a webhook.



  2. Click Settings at the top of the page.

    screenshot_248.png

  3. Select the Integrations tab, then click Webhooks.

    Integrations_Webhooks.png

  4. Enter your webhook URLs within the preferred field(s).



  5. Click Save when finished.



Testing Webhooks

To ensure your Webhooks are reporting as expected, you can use a HTTP request inspector and make a test call. The instructions below outline an example on how to test your webhooks.

  1. Click Settings at the top of the page.

    settings.png

  2. Choose the company you’d like to create a webhook.

    company_copy.png

  3. Select All Integrations from the Integrations menu on the left.

    screenshot_479.png

  4. Choose Webhooks from the list of available integrations.

    screenshot_623.png

  5. Paste the RequestBin URL from step 2 into the field of the Webhook you'd like to test.



  6. Select Activate when finished.

    screenshot_642.png

Now, place a test call to a tracking number within this company. Once you've placed the test call, you can return to the RequestBin page from step 2, and refresh the page. All parameters from your test call will be available in an easy-to-read format. 

The information provided in your Webhook parameters is dependent upon whether the call was placed to a source tracking number or a keyword tracking number

Disabling Webhooks

Disabling a company's webhooks will prevent CallRail from sending your call data to your third-party integrations. We'll keep your webhooks saved in case you'd like to re-activate your integration in the future.

  1. Click Settings at the top of the page.

    settings.png

  2. Choose the company whose webhooks you'd like to disable.

    company_copy.png

  3. Select All Integrations from the Integrations menu on the left.

    screenshot_479.png

  4. Choose Webhooks from the list of integrations.

    screenshot_623.png

  5. Select Disable Integration on the right side of the page.

    screenshot_613.png

  6. Click Disable to turn off your HubSpot integration.



Have more questions? Submit a request

Comments

Need additional help? Ask our Community!