A WebHook is a method by which one application can provide other applications with real-time information. WebHooks 'listen' for an event and once triggered, they pass data to another application using a user-defined HTTP POST URL. The other application can then itself execute one or more processes allowing a single WebHook to generate a series of customised events.
To achieve near real-time updates with traditional APIs (Application Programming Interfaces), very frequent checks need to be run against the source. As WebHooks send data to other applications as the event happens, API calls are no longer required resulting in a resource-light, highly responsive, simple notification process that is ideal for integrating Feefo into custom applications or external databases.
Feefo's application of WebHooks allows you to define a WebHook which listens for new feedback received, and then according to its configuration, can be used to send data every time feedback is added to your account. We pass a unique identifier to the WebHook for each review received which can then be used as part of a Reviews API call to download the full feedback information. Once downloaded, the review can be processed as needed and imported into your preferred system. Configuration parameters include the service/product/NPS ratings that you're interested in and whether the WebHook is triggered when the feedback is first created or when it's updated.
Configuring a Feefo WebHook is done through the Feefo Administration Portal, under 'Settings > WebHooks'. The content of the Settings page will be dependant on whether WebHooks already exist or not. If no WebHooks exist, you will see the following:
And if WebHooks do already exist, you will see a list of the existing WebHooks and the recent calls they have made, similar to the following. More details about this content is shown in Step 2.
Add a pre-shared key if required and choose Save. If defined, a pre-shared key must be between 6 and 255 characters in length and take the form of any upper/lower case letters, numeric or special characters. The pre-shared key will be included as an HTTP Request Authorization header within the call to the WebHook allowing the merchant to provide secure access to their WebHook by validating the request is from Feefo. Changing the key or removing it altogether is done by simply editing/deleting the value in the box and saving. If preferred, a pre-shared key can be added later, but once added, any existing or subsequently added WebHooks will use the pre-shared key value that's defined at the time the trigger takes place for authentication.
To create a new WebHook, click on 'Register WebHook'. This displays the 'Register New WebHook' form:
- Define a name for the WebHook in the 'Rule name' field. This name cannot be the same as a pre-existing WebHook and must be between 1 and 24 characters in length.
Now define the rules for when the WebHook runs by defining when and for which ratings it is triggered. Under 'When', decide if it runs:
- Only when the customer first leaves feedback (this is the default - choose 'is created').
- Only when the customer changes their feedback (choose 'is updated').
- When the customer first leaves or changes their feedback (choose both 'is created' and 'is updated').
Determine the rating conditions that will trigger the WebHook:
- 'Regardless of rating' - The default condition when a WebHook is first created. The WebHook will be triggered whenever a service or product review is left, whatever the rating (between 1 and 5 stars).
- 'Where the service rating is' - Configure which service ratings will trigger this WebHook. If this option is selected, the default is for all service ratings (between 1 and 5 stars) to trigger the event but a list of check boxes allows one or more service rating to be deselected.
- 'Where the product rating is' - Configure which product ratings will trigger this WebHook. If this option is selected, the default is for all product ratings (between 1 and 5 stars) to trigger the event but a list of check boxes allows one or more product rating to be deselected.
- 'Where the NPS score is' - This option will only be present if NPS (Net Promoter Score) is enabled on the account. Configure which NPS score will trigger this WebHook. If this option is selected, the default is for all NPS scores (between 0 and 10) to trigger the event but a list of check boxes allows one or more NPS scores to be deselected.
- Add the URL where we should place the data ready for your applications to process. This needs to be entered into the 'WebHook URL' field.
- Choosing 'Create' will create the new WebHook and 'Cancel' will discard the settings.
If one or more WebHooks already exist, you can view their configuration and usage from the 'Settings > WebHooks' page.
The top half of the page shows the Configured WebHooks. This is a list of all WebHooks that have been configured and the rules that apply to each one. Looking at one of the rules in detail:
- 'Rule' is the name of the WebHook.
'When' is the type of event that triggers the WebHook. Possible values are:
- Feedback is created.
- Feedback is updated.
- Feedback is created/updated.
'Where' lists the ratings where this WebHook runs. Possible values are:
- - (i.e. a hyphen). This means it runs regardless of the service and product ratings.
- Service rating is. This is followed by a series of service ratings separated by a / (i.e. a forward slash). In this example, the rule is configured to run when the service rating is 1, 2 or 3 stars.
- Product rating is. This is followed by a series of product ratings separated by a / (i.e. a forward slash).
- NPS rating is. This is followed by a series of NPS scores separated by a / (i.e. a forward slash).
- 'Call WebHook URL' is the URL that the WebHook passes data to. It must be a valid URL in the form of https://www.merchant_domain.com.
- An 'Edit' button that displays a form for editing the WebHook. This form is identical to the one shown when creating a new WebHook except it is displayed pre-populated with the current settings for the WebHook. If anything needs changing, edit as needed and then choose 'Update' to save the changes or 'Cancel' to discard them.
- A 'Delete' button that gives you the option to completely remove the WebHook. Conrifmation is required before the WebHook is deleted.
- The bottom half of the page shows the Recent WebHook Calls. This is a list of the 20 most recent WebHook calls, with the most recent call at the top. Looking at one of the calls in more detail:
- The date and time the WebHook call was made.
- The name of the rule that triggered the request.
- The WebHook URL which was called.
A 'View' button that displays the payload (data) that is passed to the URL location.
- This example includes the WebHooks pre-shared key for this account (shown as the value after "hmac") and a Reviews API call to a single review.
- 'Result' displays the HTTP status code for the WebHook submission, HTTP 200 indicating that this was successful. For full details about HTTP status codes, see https://en.wikipedia.org/wiki/List_of_HTTP_status_codes.
- The top half of the page shows the Configured WebHooks. This is a list of all WebHooks that have been configured and the rules that apply to each one. Looking at one of the rules in detail: