Skip to main content
A webhook can be seen as a reverse API. Instead of a user polling an API endpoint in a system (Engage, for example) to check for new data, the user can instead configure an URL in that system that can be called only when there is new data. This, essentially, is a webhook. Structurally, a webhook is just a HTTP POST to an open API. They are simpler than an API endpoint, but have less functionality. Webhooks, for example, don’t allow pushing, deleting or updating data in another system, only receiving data. When you’re only sending specific data occasionally webhooks are a good solution.
Since you only receive data over a webhook when an event occurs, if the other system doesn’t call your webhook with data you can’t be sure if it’s because no events are occurring or if the other system is down. Keep this in mind.
The advantages of webhooks are therefore:
  • A simpler integration
  • Less data being passed
  • No polling needed
  • Updates only sent when changes happen

​
Webhooks currently available

Currently these webhooks can be used in Engage:
This webhook with the ID contact.acceptsEmail.changed is triggered whenever the acceptsEmail preference changes for an already existing contact.
This webhook with the ID contact.acceptsSms.changed is triggered whenever the acceptsSms preference changes for an already existing contact.
This webhook with the ID contact.acceptsPostal.changed is triggered whenever the acceptsPostal preference changes for an already existing contact.
This webhook with the ID loyalty.addPoints is triggered whenever points are added to a contact via the Engage UI or through an automation. The transaction is sent in the webhook.
This is used only for customers using the point follower solution.
This webhook with the ID point.balance.updated is triggered whenever a contact’s point balance has changed.
This webhook with the ID reward.voucher.created is triggered whenever a reward voucher is created for a contact.
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.

​
Requirements for webhooks

Here are the various requirements you’ll need to implement a webhooks solution.

​
Basic client requirements

To receive webhooks from Engage you will need to develop and deploy a web service. This is basically an API with a POST endpoint. It’s common to use one service for all webhooks and then distributes the incoming events internally to your different systems.
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.

How to consume webhooks using Svix

​
Technical client requirements

You, the client, must develop functionality to verify the webhooks are from the correct sender.

How to verify payload using Svix

 Voyado’s webhooks service (Svix) has SDK:s and libraries to handle most of what is needed. Libraries are available in Go, Python, Typescript/Javascript, Java, Kotlin, Ruby, C# (dotnet), Rust, PHP.

Code libraries available for Svix

 You can see source IP addresses here. This integration uses the EU region. It’s possible to add custom headers to webhooks and also rate limiting, if needed. If you want to use the optional feature of end-to-end encryption, you must develop functionality to decrypt the payload data (in the same way as with soft identification.
https://mintcdn.com/voyado/-QD3xMpfEY3BtcMt/icons/developer-link.png?fit=max&auto=format&n=-QD3xMpfEY3BtcMt&q=85&s=92be9e7202a0fc63f959e3f367cc7e32

Read more soft identification
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.

Read about GDPR sub-processors

​
Setting up webhooks in Engage

Once you have created your webhooks, you’ll need to set them up in Engage. The steps are:
1

Enable webhooks in Engage

Contact your Voyado account manager to enable webhooks in your Engage instance. Depending on your agreement, a supplement might be required. The webhooks module must then be activated in the Engage back-end, and the correct permissions granted to users.
2

Configure client endpoint

Now you’ll configure the client endpoint in the Engage UI. Start by going to Administration/Webhooks Dashboard to see all the Webhooks already set up. Select + Add Endpoint to add another.
Webhooks already set up
3

Choose events to use

After adding your endpoint, select it and then choose which event you want to send to it:
Choose event to send
4

Add verification and encryption

Get the Signing Secret used for verification, as well as the Payload Encryption Key (if you are using it) from your Voyado account manager. When sending these to somebody else, 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.
Choose event to send
5

Test your webhook

You can use the “Testing” functionality in Svix to send test-events to the endpoint. Check the log for errors.
6

Configure a rate limit (optional)

If you need it, configure a rate limit so the client endpoint can handle the load.
7

Configure a custom header(optional)

You can also choose to 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 seen as many nested layers.
  1. The webhook itself: No security.
  2. 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.
  3. IP lock: Messages can only be accepted from specific IP addresses.
  4. 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.
While the client decides how many layers to implement, layers 1 and 2 above are the absolute minimum.