Webhooks are a way to notify an application outside of ChurnZero that a contact has reached a particular point in a Play. Webhooks have become a very popular way to configure inter-application communication without the need for developer interaction. 

How does it work?

It is common for software applications to have to communicate with each other. Previous to webhooks, this was often accomplished via Application Programming Interfaces (or API's). With an API, you would typically write a custom application that would call the API and ask - "hey, did this contact reach this point in the play yet?". If you get back a yes, you might have to make another call to get all the details needed for your other systems. This is called polling and is not technically real time.

Webhooks turn this model upside down and allows you to subscribe to notifications. When a contact has reached a particular step in the play, we send you an notification with all the data you asked for when you configured the step.

Requirements (the technical stuff)

Before you get started with webhooks, it is important to understand what is required. First, you will need another system to accept the notification. This can either be an internal system that is custom to your company, or another third party system that has an available API (such as your CRM). This API will need to accept a POST HTTP call that accepts values either via a JSON post body or via URL parameters.

Second, you will want to configure an email address where you can receive notifications of failures that might occur due to inability for ChurnZero to call the configured webhook. More on handling errors later.

Configuring a Webhook

Okay, you have a system that needs to be notified when users hit a certain play step, great! Use the below steps to configure a new webhook play step.

We are going to assume you have an existing ChurnZero Play to work with, or that you will create a new one.

1. Edit the desired play
2. Navigate to the Steps page
3. Choose to add a new step and choose "Call Webhook" as the step type. You should see a screen that looks like this:
   
   
   
   
4. URL: This is the endpoint of the API that you want to call, in other words, the receiving application of the notification.
   
   
5. Content Type: How do you want us to send you data?
   • Json will send the data in the POST body (application/json)
   • Url Encoded will send the data on the URL as name/value pairs (x-www-form-urlencoded)
     
     
6. Email Errors To: Supply one or more emails that should receive errors should something go awry. This is a required field and provides a way to be notified should there be something wrong with the webhook configuration.
   
   
7. Post Data: A list of name/value pairs of data to send. All applicable merge fields are available (e.g. Contact Email, Account Name, etc...). If using merge fields, the data that is sent will be injected at the time of executing the play step. Note that there is a drop down list of available merge fields to choose from. Example:
   
   
   Note: Once a merge field is chosen from the drop down, the proper merge field name will be inserted.
8. Once you have your webhook configured, it is a good idea to test it. The Test Webhook button will make a test call with all of the configured options. This lets you ensure your webhook is working prior to executing your play.
   
   
9. Save your changes!

Example

In this example we will use a handy little webhook test site simply called Webhook Tester which can be found at this url: http://webhook.site. If you navigate to this site, it will give you a temporary URL that you can use and send data to. 

• First, lets navigate to http://webhook.site to get a test webhook url. You should see something like the following:
  
  
  
  **Important: Webhook Tester is an open source project provided free of charge under the MIT License by FredSted. ChurnZero has no affiliation with the author of this site.
  
  
• Next, I will configure the webhook play step to use the test webhook URL. The configuration should look something like this:
  
  
  
  
• Time to test the webhook so lets click the Test Webhook button. If all goes well, we should see the following confirmation:
  
  
  
  
• Looks like it worked! Let me go check the http://webhook.site page to see if I received the data I expect:
  
  
  
  The above screen from the webhook test site shows that the POST went through along with the data that was posted. 
  
  
• If the webhook post call had failed, instead of the successful confirmation message I received above, I would instead see a message that shows the error response received from the call. For example, if I change the URL to our test webhook slightly and click the Test Webhook button again, I would see the following:
  
  

Technical Details

Headers

Included in each post is the following HTTP header information:

• X-CHURNZERO-EVENTTYPE
  Represents the event type that triggered the webhook call. When executed through a play, the text "Play" will be sent. In the case of a test (triggered by the Test Webhook button), the word "Test" will be sent.
  
  
• X-CHURNZERO-EVENTNAME
  The name of the event (in our case the name of the Play). 
  
  
• X-CHURNZERO-EVENTID
  The ID of the event that triggered the webhook call (e.g. the Play record identifier).

Post Data

The data that is posted is configured in the Play step as shown above. When posting data, this is what is included:

• Json (application/json)
  Json data is provided in the following format:
  
  
  
  Note that for Merge Fields we include the merge field name in the post data. For custom arguments and values, only the name/value fields are included.
  
  
• Url Encoded (x-www-form-urlencoded)
  Url encoded data is supplied via name/value pairs on the URL. For example:
  
  http://mywebhooktest.com/myendpoint?account_name=NA&contact_email=foo%40bar.com&my_custom_arg=My%20Custom%20Value 
  
  Note that the values are URL Encoded so instead of foo@bar.com, instead you get foo%40bar.com.   

Error Handling

ChurnZero uses the following logic when attempting to post data to your webhook:

1. When the play executes, we will call the supplied Webhook for each contact that reaches this step in the play.
   
   
2. In the case of an error calling the webhook, ChurnZero will try again with a short delay (approx. 5 seconds). We will attempt the call up to 3 times with a 5 second delay and if we still receive an error an email will be sent to the configured "Email Errors To" email addresses.
   
   
3. The step will then be scheduled to try again 1 hour later.
   
   
4. If, after 3 rescheduling attempts we are still receiving errors, ChurnZero will fail the play step. Additional play steps that follow the Call Webhook step will continue to be executed and the Play report will show a failure statistic for the failed contact.