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 calls 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.

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

  • tracking 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
  • received time
    • The timestamp for when the message was received 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.



  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. In this example, we'll use the service provided by requestb.in. From the RequestBin homepage, click Create a RequestBin.



  2. RequestBin will provide a URL at the top of the page. Copy the URL to a text edit for use in the next step, but keep the requestb.in page open.



  3. In a new window or tab, log into your CallRail account, and select the company where you'd like to test the webhook.



  4. Select Settings from the top of the page.



  5. Select the Integrations tab, then choose Webhooks.

    Integrations_Webhooks.png

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



  7. Select Update when finished.



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 Integration

Disabling a company's webhooks integration 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. Choose the company whose integration you'd like to disable.



  2. Click Settings at the top of the page.



  3. Select Integrations from the secondary menu, then click Webhooks.

    Integrations_Webhooks.png

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



  5. Click Disable to turn off your webhooks.



Have more questions? Submit a request

Comments

Was this article helpful?