Webhooks for contact preferences
A contact's preferences are what tells you if the contact has agreed to receive marketing information by email, SMS, post, or not at all. The three preferences in use in Engage are:
acceptsEmail
acceptsSms
acceptsPostal
As a retailer, you will often need to show the contact preferences for a contact, on My Pages or at the checkout, and you need to be sure the values shown are correct before they are used, or changed over the Engage API. Since Engage is the master of these settings, the preferences will either have to be fetched every time they are needed, or some system needs to be put in place to constantly poll Engage for the current values. This is not very efficient.
It's better if you always have the correct values in your systems. Engage allows this using webhooks, through Svix, Voyado's webhooks service provider. Webhooks are a way for Engage to push events out to the client's systems. In this case, the client creates a webhook for the systems they want to keep updated about contact preference changes. Then, whenever a preference is changed in Engage, the webhook is used to inform all the subscribed external systems, keeping them all in sync with Engage.
Webhooks allow a simpler integration, with less data being passed, no polling needed, and updates only sent when a change is made.
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 distributes the different events internally to your different systems.
Tip
While 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 available over the internet. Fixed source IP addresses may 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).
Legal requirements
When moving to a production environment, you'll need to approve Svix 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.