Each product at Truora has events that your system might find useful to monitor in order to trigger an action. Some examples of these events are: a check completion, a validation failure, and a WhatsApp conversation delivery, among others. In this guide, you will learn creating a rule using our web application in order to listen to these events and notify your services via webhooks.
Disclaimer: Webhook configuration requires an understanding of APIs and authentication schemes, so we recommend you have a developer or tech-savvy person do or help during this process
A rule is an event that triggers a series of tasks, called actions. An example of a rule that leads to actions could be “when a check is created, send a webhook and an email”. Check creation would be the triggering event for the rule and the actions would be sending a webhook and sending an email.
Now, we will have a step-by-step guide on how to create a rule that sends a webhook to a given endpoint once a check of types “person” or “vehicle” finishes.
To create a rule, we will first need to log in to Truora. After that, we can access the Webhooks/automations section via the sidebar:
In that section, there will be an empty list of available rules. To create a new one, we need to click the “New rule” button.
This will redirect us to the rule creation view. In the first section, we can set our new rule’s name and optionally a description. After that, we can set the product for which we will trigger actions. For this guide, we will use our TruChecks product.
As soon as you choose the product, a dropdown of subproducts will appear. We will select “check” in this case since we want to trigger the rule per finished check.
Setting the desired subproduct will allow you to select which events the rule should listen to. Even though you may have multiple events per rule, we will only need “Completed” for now.
Our final step for our rule will be adding a condition. This optional step will enable us to filter this rule depending on the values that check variables may take. For this example, we only want checks of types “person” or “vehicle” to trigger the webhook. Hence, we will click the “Add conditions” button right below the selected event. A simple rule comparing the check type with “person” OR “vehicle” will be enough. We will create two condition groups because groups are formed with the OR operator.
Once the rule’s name, product, subproduct, events, and conditions have been specified, we can now choose which actions to trigger.
We will choose the webhook which will ask for the action’s name, an e-mail, and credentials in case your endpoint requires them for authentication. Credentials are safely encrypted and stored in our services. They will also be available to use in the steps to follow. Fill all of these out before proceeding to the endpoint definition.
Regarding the webhook request, Truora webhooks perform a request as a JWT. This is a compact and self-contained way to transmit information securely between two parties in the form of a JSON object. The service that receives this hook should not only decode the token but perform the required validations over its data to detect any alterations. It should also verify its signature which will be provided during these steps but also sent via e-mail, so make sure you set the address correctly while setting up the webhook.
Once you have filled out the previous fields you can set up the endpoint that will be triggered. You can look at what an encoded and decoded JWT look like by clicking the “Body” tab.
If your endpoint requires credentials as part of the request, you can set them in the request params or headers by clicking any of those two tabs and setting the key and value. To insert a previously created credential or an event variable, click on the “+” button in the Value field and choose the desired option. This will add the reference to the request.
We will save our action by clicking the “Save action” button in the bottom right. This will show us the action we just configured and the option of adding more. Since we have everything we need, we will now click “Save actions” and “Finalize rule configuration”.
Finally, a pop-up will appear warning us the rule will be created and enabled immediately. We accept by clicking “Save rule” yet again.
You have created a rule successfully! You should now be able to see your rule, its name, ID, status, and creation date. In case you want to update it or disable it, you can do so by clicking on the three dots button on the right. Feel free to create your own rules and check out what other events we support.