Summary
Webhooks are a way that you can integrate external systems with Planhat, as well as interact with the Planhat API
Planhat includes customizable Automation Templates for notifying a webhook in response to a range of trigger events
You can also build Custom Automations triggered by an incoming webhook, and/or that call a webhook as an action step
If you would like to build an advanced Automation with webhooks, you should speak with your Planhat TAM/CSM for assistance
Who is this article for?
Planhat Users who are building Automations for their organization (e.g. Tech/Ops)
Series
This article is part of a series on Automations:
Webhooks in Automations ⬅️ You are here
Article contents
This is a technical deep-dive article
Read on if you'd like to learn about using webhooks when configuring Automations.
If you would simply like a general introduction to Automations, check out our overview article here.
What are webhooks, and where can they be used in Automations?
Webhooks are a way that different applications can send information to one another, in response to a specific event.
In the context of Planhat, they can be used to send information from Planhat to an external application (e.g. a notification), they can be used by an external application to send information into Planhat (e.g. a survey response), and they are just one way that you can interact with the Planhat API.
When it comes to Planhat Automations, there are three main places where you can see/use webhooks:
In the Apps Library, you'll find many Automation Templates in the "Send a Notification" category that enable you to notify a webhook in response to a wide variety of possible trigger events in Planhat
Click the image to view it enlarged
When building a Custom Automation, you can have an incoming webhook as the trigger event
Click the image to view it enlarged
When building a Custom Automation, you can call a webhook in a step
Click the image to view it enlarged
Why use webhooks in Automations?
You can use webhooks in Automations to send data to/from Planhat - for example:
When an End User's NPS changes in Planhat, notify a webhook
When a Company's Health Score changes in Planhat, notify a webhook
When an Invoice is updated in Planhat, notify a webhook
When a survey response is received by an external survey provider, send the survey response data to Planhat via a webhook
Webhooks are also a great way to interact with data in Planhat via our API. For example, you can "GET" (retrieve) data, "POST" (create) data, and so on.
📌 Important to note
Details of the Planhat API are out of the scope of this article, but you can check out our extensive API documentation for further information, and/or consult your Planhat Technical Account Manager (TAM).
How to use webhooks in Automations
As we mentioned earlier in this article, there are several different ways that you can use webhooks in Automations.
Templated Automations - "Notify a webhook"
If you would like to notify a webhook in response to a trigger event in Planhat, then you should create a Templated Automation - there are 20 different "Notify a webhook" Automation Templates in Planhat's Apps Library (see screenshot below), each for a different trigger event (e.g. when a Company is created, or when an Owner is assigned, etc.).
📚 Further reading
For full details of how to set up Templated Automations, please refer to our separate article here. In this webhooks article, we will just summarize some key points.
Click the image to view it enlarged
🚀 Tip
Remember (from the main Templated Automations article) that you can use the search box in the top right of the Apps Library to find relevant Templates more quickly - in the screenshot above, we have typed in "webhook" to filter the Templates.
As with other Automation Templates, you can customize each of these webhook-related Templates to make them suit your particular requirements. Let's take a look at an example - "Notify a webhook when a Company changes Phase":
In this Automation Template, you can:
Choose a Company filter, to determine which Company records to include in the trigger
Choose a Phase value to be included in the trigger
Enter your desired webhook URL
Select whether the payload is JSON or Form
Modify the pre-populated custom message - note the use of dynamic replacement codes, which you can read all about in our separate article here
As you can see, even when using a Template, you have a great deal of flexibility.
If you can achieve your goal by creating a Templated Automation you should do so, before considering a Custom Automation.
Custom Automations - "Incoming webhook" trigger
There are actually two different places where you can use webhooks in Custom Automations, so we'll go through each of these in turn.
📚 Further reading
For full details of how to set up Custom Automations, please refer to our separate article here. In this webhooks article, we will just summarize some key points.
The first place is within the trigger. This is an "incoming webhook" - i.e. a webhook will be used to send data into Planhat from an external app., such as a survey provider.
When you are building a Custom Automation, you will see "Incoming webhook" as a trigger option, towards the bottom, in the "Connected Apps" category.
Click the image to view it enlarged
Selecting this will load a webhook trigger configuration panel as pictured below.
Click the image to view it enlarged
If you leave the dropdown menu as "anything", then you don't need to configure anything further here. You will be giving a unique URL from this Automation trigger to your external app (which we describe shortly) so it will send the data via the webhook specifically to this Automation, so it's targeted/filtered in that way.
If you select "specific properties", you can build rules here.
Once you have set up your "Incoming webhook" trigger, you should proceed with creating the first step of your Automation. Once you have created at least one valid step (and given your Automation a name), you will be able to save your Automation (i.e. the orange "Save" button in the top right will be enabled).
When you then open up your saved Automation, you will see that a "Copy URL" button has appeared on the webhook trigger (shown below). Click this to copy the unique URL for this webhook so you can paste it into the external app that will be sending the webhook (e.g. your survey provider).
Click the image to view it enlarged
🚀 Tip
If you want to build your Automation step-by-step, e.g. you want to see the data received in the trigger via the incoming webhook before you then build your steps (check out our worked example below for an example), you can use a Wait step temporarily (like in the example screenshot above) in order to save the Automation and test the trigger, and then simply replace it with your "real" step(s) once you have the information required to build them.
Once you've saved your Automation and enabled it in the App Center, you can trigger it. For example, if your incoming webhook is from a survey provider, you could answer the survey as a test user, or perhaps your survey provider has a "test" button that sends example data to help you test the webhook. You can then open up the "Event details" of the Automation logs (which you can read all about in our separate article here), to see what's been sent in the incoming webhook. This information can then be really useful when you're building subsequent steps, which we'll talk through in the worked example later in this article.
📌 Additional technical details
Security for incoming webhooks is implemented through several mechanisms:
Unique URL (UUID-based)
Each webhook URL is assigned a unique UUID (as previously mentioned), which makes it difficult to guess or brute-force
The UUID is long and random, providing a strong layer of security
HTTPS encryption
Data transmitted via the webhook URL is encrypted using HTTPS, ensuring confidentiality and protection from interception
Header validation
Planhat allows you to define rules for validating incoming requests by checking HTTP headers
This validation ensures that requests are coming from trusted sources only
Payload validation
In addition to validating headers, you can also validate the data contained within the payload itself for an extra layer of security
This involves defining rules or conditions that the payload data must meet before processing, such as verifying specific fields or checking digital signatures included in the payload.
Only POST requests are accepted. Any other HTTP method (e.g., GET, PUT, DELETE) will be rejected.
The payload must be sent in the body of the POST request
If you would like to discuss any of these points in further detail, please reach out to your Planhat Technical Account Manager (TAM)
Custom Automations - "Call a webhook" step
The other place where you can use a webhook in a Custom Automation is within an action step. This is where you "Call a webhook" to carry out an action of your choice.
When you go to add a new step, you'll find "Call a webhook" as a option in the "Connected Apps" category.
Click the image to view it enlarged
When you select this type of step, you'll see a configuration panel like this:
Click the image to view it enlarged
Within the "Webhook" section, you:
Use the dropdown to choose between:
GET (retrieve) data from the URL
POST (create) data to the URL
PUT (update) the entire data on the URL
PATCH (update) targeted pieces of data on the URL
DELETE (erase) data on the URL
Type your desired URL into the box
🚀 Tip
The URL in the example screenshot above is linking to the Planhat API. Communicating with the Planhat API is a common use case of these "Call a webhook" steps. We talk through this example in more detail below.
In the "Headers" section, you can use the dropdown box to select your choice of "Content-Type" - "application/json" and so on.
Worked example of a Custom Automation with webhooks
Now you understand the principles of using webhooks in Custom Automations, let's bring this together in a full worked example. (We are not going to go through webhooks in Templated Automations again because that's pretty simple, and we already went through an example above.)
🚀 Tip
If you need any help with setting up Automations - particularly relatively complex ones such as Custom Automations involving webhooks - then please speak with your Planhat Technical Account Manager (TAM).
In this example, we're using an external third-party provider to send a CSAT survey to our customers, and then we want the survey responses to be automatically sent into Planhat and be saved on the relevant End User record. We use a webhook in the trigger and in the first step, and reference the webhook step in the second step too. Our completed Automation flow chart looks like this:
Let's go through all the component elements of this Automation, clicking on each box in the flow chart in turn to open up its configuration panel on the left-hand side. You will see that we use information from the logs of the trigger to help configure the steps; you are likely to create an Automation like this in a stepwise manner (e.g. testing the trigger before building the action steps), rather than all at once.
Trigger - "Incoming webhook"
The Automation is triggered by an incoming webhook.
Click the image to view it enlarged
Although this is trigger is set to "anything", we have linked this Automation to our external survey tool by clicking on the "Copy URL" button in Planhat as shown in the screenshot above (remembering that we need to save the Automation for this button to appear), and pasting that URL into the relevant field in our survey provider.
When we trigger the Automation (e.g. by using the "Send test" button in our survey provider, or by answering a survey), we can see the data sent into Planhat by opening up the "Event details" in the Automation logs, as we mentioned earlier in this article.
"Call a webhook" step
The first step of the Automation is a "Call a webhook" step.
Click the image to view it enlarged
In this example, we have chosen "GET" as our action, and the URL entered in the box after it is:
https://api.planhatdemo.com/endusers?email=<<update.event_data.person.email>>
This step is actually interacting with Planhat's API, which you can read about in our separate documentation here.
📌 Important to note
The standard base URL for CRM (rather than time-series data) API requests using the Planhat API is: https://api.planhat.com. In this example we use https://api.planhatdemo.com instead, because this Automation has been built in a Planhat tenant in the demo cluster, as shown in the Planhat tenant URL. You may need to modify the URL for your particular Planhat tenant. Speak to your TAM if you need help with this.
In this step we are "Getting" the Planhat End User that's referenced in the trigger event (the incoming webhook). The text inside the << >> is a dynamic replacement code, which you can learn about more generally in our separate article here.
We actually get the specific replacement code (<<update.event_data.person.email>>) by looking at how the data is structured within the "Event details", i.e. the logs of the trigger, as we mentioned above - see the screenshot below. This replacement code is telling the step where to find the email address in the data received from the incoming webhook, and then adds this email address into the query, so we "Get" that End User.
🚀 Tip
We have also renamed this step to "Step 1", from the automatically generated random code name (e.g. "s-iOY"). This is optional, but means it's a bit clearer in the flow chart and the logs, and makes it easier to reference in any subsequent steps (which we'll go on to next).
📌 Important to note
In this step we are "Getting" an existing Planhat End User, so make sure the person answering the survey in the incoming webhook has already been added to Planhat.
"Update End User" step
Finally, in Planhat we want to update the End User we have just "Got" with their survey responses. We use an "Update End User" step. Our configured step looks like this:
Click the image to view it enlarged
As you can see, we use more dynamic replacement codes.
The first row of fields, "id" (grayed out), is specifying which End User we want to update. We use the replacement code <<Step 1[0]._id>>.
"
Step 1" is referring to the previous step (which we renamed to "Step 1")We use "
[0]" in this case because we are referring to the first element in an array (of End Users in Step 1)"
_id" is the Planhat ID of the End User
... basically this is just saying we want to update the End User we retrieved in Step 1. (Remember, we hadn't renamed the previous step to "Step 1", we would need to use whatever its name was instead within this replacement code.)
In the next row, we select "CSAT Score" (a custom field we had created on the End User model), and then use the replacement code <<update.event_data.score>>. A bit like in Step 1 where we used a replacement code to specify where to find the email address in the trigger data (the incoming webhook data), here we are specifying where to find the "score" property, and we get this information by looking at the "Event details" in the logs, as shown in the screenshot below.
In the final row, we select "CSAT Comment" (a custom field we had created on the End User model), and then use the replacement code <<update.event_data.comment>>. Just like we just saw for the score, we get this replacement code by looking at the "Event details" of the logs to identify where the comment data is located.
📌 Important to note
You will need to create your chosen fields in Planhat first before you can select them when configuring your Automation. You can read more about building custom fields here.
Final result
Once we've finished building our Custom Automation, we test it (in this case, using the "Send test" button in our survey provider), and we can see the survey response is correctly being added to the relevant End User.
Click the image to view it enlarged