IMPORTANT: We're updating product naming across our documentation. Engage is now Customer Engagement and Elevate is now Product Discovery. This doesn't change Voyado's services, functionality, or terms of your agreement. Be aware, as these changes happen, that you may see both the old and new names being used.
A webhook can be seen as a reverse API. Instead of a user polling an API endpoint in a system (Customer Engagement, 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 might be a good solution.
You only receive data over a webhook when an event occurs. So 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.
Currently these webhooks can be used in Customer Engagement:
Contact preferences for email changed
This webhook with the ID contact.acceptsEmail.changed is triggered whenever the acceptsEmail preference changes for an already existing contact.
Contact preferences for SMS changed
This webhook with the ID contact.acceptsSms.changed is triggered whenever the acceptsSms preference changes for an already existing contact.
Contact preferences for postal changed
This webhook with the ID contact.acceptsPostal.changed is triggered whenever the acceptsPostal preference changes for an already existing contact.
Contact consent changed
The webhook with the ID contact.consent.changed is triggered for changes in consent-typed fields on a contact.
Points - added
This webhook with the ID loyalty.addPoints is triggered whenever points are added to a contact via the Customer Engagement UI or through an automation. The transaction is sent in the webhook.
This is used only for customers using the point follower solution.
Points - balance updated
This webhook with the ID point.balance.updated is triggered whenever a contact’s point balance has changed.
Vouchers - created
This webhook with the ID reward.voucher.created is triggered whenever a reward voucher is created for a contact.
Multichannel promotion assigned
This webhook with the ID promotion.multiChannel.assigned is triggered when a multichannel promotion is assigned to a contact in Customer Engagement.
Contact created
This webhook with the ID contact.created is triggered whenever a new contact is created in Customer Engagement.
Contact updated
This webhook with the ID contact.updated is triggered whenever a new contact is updated in Customer Engagement.
Contact deleted
This webhook with the ID contact.deleted is triggered whenever a new contact is deleted in Customer Engagement.
Read more about how each webhook event can actually be used in the use-cases article:
See the webhook use-cases
Even though you are free to configure subscriptions to all the available events, you’ll still need to reach out to your Voyado Account Manager or Voyado support to activate the events that you want to subscribe to, so that the data actually gets sent from Customer Engagement.
To receive webhooks from Customer Engagement 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 distribute 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 Customer Engagement 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.
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 SDKs and libraries to handle most of what is needed. Libraries are available in Go, Python, Typescript/Javascript, Java, Kotlin, Ruby, C# (dotnet), Rust and 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.
When you are implementing webhooks in Customer Engagement and move to a production environment, you’ll need to approve Svix (Voyado’s webhooks provider) as a GDPR sub-processor.
The security involved in using the webhooks solution can be seen as many nested layers.
The webhook itself: No security.
Signing the webhook message with Signing Secret: The recipient can use this to 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: By using this, messages can only be accepted from specific IP addresses.
Payload encryption: All data from Customer Engagement is encrypted with a key that only Voyado and the client know. It is configured in Customer Engagement, meaning that Svix cannot read any of the data that passes through it.
While it is the client themselves who decides how many layers to implement, layers 1 and 2 above are the absolute minimum.
Once you have created your webhooks, you’ll need to set them up in Customer Engagement. The steps are:
1
Enable webhooks in Customer Engagement
Contact your Voyado account manager to enable webhooks in your Customer Engagement instance. Depending on your agreement, a supplement might be required. The webhooks module must then be activated in the Customer Engagement back-end, and the correct permissions granted to users.
2
Configure client endpoint
Now you’ll configure the client endpoint in the Customer Engagement UI.Go to Administration/Webhooks Dashboard to see the Webhooks already set up.Then 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.
If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled and an operational webhook (EndpointDisabledEvent) will be sent.For example, if your receiving service responds with 404 for whatever reason, such as as a contact not being present, over a 5 day period, this behaviour is triggered and the endpoint will be disabled. See more details at the Svix docs:
Read more about failing endpoints
Assistant
Responses are generated using AI and may contain mistakes.
