Using webhooks in Engage
Engage allows you to use webhooks when integrating it with your system. Webhooks allow a simpler integration, with less data being passed, no polling needed, and updates only sent when a change is made. See here for a quick and basic introduction to webhooks.
Webhooks currently available
Webhooks functionality is being built out and currently these webhooks can be used in Engage:
Webhook | Name | Triggered when: |
|---|---|---|
Contact preferences - email | contact.acceptsEmail.changed | The acceptsEmail preference changes. |
Contact preferences - sms | contact.acceptsSms.changed | The acceptsSms preference changes. |
Contact preferences - postal | contact.acceptsPostal.changed | The acceptsPostal preference changes. |
Points - add | loyalty.addPoints | Points are added to a contact via the Engage UI or through an automation. The transaction is sent in the webhook. (Only for customers using the point follower solution.) |
Points - balance updated | point.balance.updated | A contact's point balance has changed. |
Vouchers - created | reward.voucher.created | A reward voucher is created for a contact. |
Note
Expanding webhook coverage is in the Engage roadmap. Ask your Voyado PM for more about what's planned, or for information on how the current webhooks are being used.
Basic client requirements
The first thing you need to do is develop and deploy a web service to receive webhooks, basically an API with a POST endpoint. It's common to use one service for all webhooks which then distributes the incoming events internally to your different systems.
Tip
When developing your webhooks, a service like Svix Play or ngrok can be used to receive webhooks from the internet on your local development machine.
Your web service must be accessible over the internet. Fixed source IP addresses can be used if your endpoint is behind a firewall or NAT.
There should be no authentication at the receiving endpoint. Instead, you'll verify that the events received are sent from Voyado Engage using signatures and a shared signing secret.
The service you provide must be able to scale with the load.
Voyado's webhooks service provider Svix has good documentation on how to consume webhooks.
Technical client requirements
You, the client, must develop functionality to verify the webhooks are from the correct sender. See here.
Voyado's webhooks service (Svix) has many SDK:s and libraries to handle most of what is needed. There are libraries available in Go, Python, Typescript/Javascript, Java, Kotlin, Ruby, C# (dotnet), Rust, PHP. See here.
You can see source IP addresses here. This integration uses the EU region.
It's possible to add custom headers to webhooks.
Rate limiting, if needed, is also possible.
If you want to use the optional feature of end-to-end encryption, you, the client, must develop functionality to decrypt the payload data (in the same way as with Soft identification).
Webhooks legal requirements
When you are implementing webhooks in Engage and move to a production environment, you'll need to approve Svix (Voyado's webhooks provider) as a GDPR sub-processor.
Setting up webhooks in Engage
Once you have created your webhooks, you'll have to set them up in Engage, This you can do yourself or with help from a Voyado support/application specialist. The steps are:
Contact Support or your technical contact to enable webhooks in your Engage instance (the webhooks module must be turned on in the Engage back-end and the correct permissions granted to users).
Now you'll configure the client endpoint in the Engage UI. Start by going to Administration/Webhooks Dashboard:
Here you can see all the webhooks already set up. Select "Add Endpoint" to add another.
After adding your endpoint, select it and then choose which event to send to it:
Get the Signing Secret used for verification, and the Payload Encryption key from your Voyado team (if you are using it). When communicating these, be careful to use the same trusted method as when sharing API-keys. The Signing Secret is created and handled by Svix, and can be rotated if needed.
You can use the “Testing” functionality in Svix to send test-events to the endpoint. Check the log for errors.
Optionally: Configure a Rate Limit so the client endpoint can handle the load.
Optionally: Configure a custom header with some kind of token to further increase security.
Security layers
The security involved in using the webhooks solution can be viewed as many nested layers.
The webhook itself: No security.
Signing the webhook message with Signing Secret: The recipient can verify that the webhook comes from Voyado. The Signing Secret is found in the portal (meaning that Svix controls it). The client can rotate the key whenever they want.
IP lock: Messages can only be accepted from specific IP addresses.
Payload encryption: All data from Engage is encrypted with a key that only Voyado and the client have. It is configured in Engage, meaning that Svix cannot read any of the data that passes through it.
The client decides how many layers to implement. Levels 1 plus 2 are the absolute minimum.