Webhook notifications
A webhook enables Voucherify to send real-time updates to your app or url endpoints. Updates are triggered by some event or action by Voucherify, and pushed to your URL via HTTP requests.
Instead of polling data from the endpoints, you can configure webhooks to get notified about triggered events, distribution channels, loyalty programs, and referral programs.
Contents:
- Project-based notifications
- Distribution channel
- Loyalty program
- Referral program
- Responding to a webhook
- Re-enabling a webhook
- Authentication
- IP Whitelisting
Project-based notifications
Project level notifications can be configured in the Project Settings.
The following 30 events can trigger a webhook notification configured from the dashboard. To see the entire list of webhooks that are configurable, see the API documentation.
Redemption | Voucher |
redemption.succeeded |
voucher.published |
redemption.failed | voucher.created |
redemption.rollback.succeeded | voucher.updated |
redemption.rollback.failed | voucher.deleted |
Campaign |
voucher.enabled |
campaign.enabled |
voucher.disabled |
campaign.disabled | voucher.loyalty_card.points_added |
campaign.deleted | voucher.gift.balance_added |
campaign.created |
Validation Rules |
campaign.updated |
business_validation_rule.assignment.created |
campaign.vouchers.generation.completed | business_validation_rule.assignment.deleted |
Customer | business_validation_rule.created |
customer.created | business_validation_rule.deleted |
customer.deleted | business_validation_rule.updated |
customer.rewarded | Publication |
customer.rewarded.loyalty_points | publication.succeeded |
customer.consents.revoked | |
customer.consents.given | |
Get notified when a webhook does not reach the destination
You can set up a notification in the Notification Center > Account Settings to inform you via Email or in the App that a webhook did not reach the destination.
Create URL endpoint
To add endpoint URLs, simply navigate to Project settings and in the General tab, scroll down to the Webhooks section. Voucherify makes it possible to define multiple webhooks.
To add one, click on the plus sign.
Start off by providing a target URL.
You have 2 options:
- Call a webhook for every listed event
- Call a webhook for a specific event or a subset of events
When you are finished with configuring the webhook, confirm the settings with Create endpoint.
From now on, when Voucherify will log chosen event(s), your endpoint will be called with event specific information in the payload.
Test an Endpoint
You can send a test webhook by clicking Send test webhook.
Update an Endpoint
To update a webhook configuration, click the pencil, apply your changes and then confirm with Update endpoint.
Delete an Endpoint
Click on the trash can icon and click Delete.
Distribution channel
Distributions send messages in response to some predefined actions (events) taken by the end-customer. A webhook can be a message channel in your distributions. As a result, when distribution conditions are met, a message is sent using the webhook. Read more about distributions here.
The table below shows which distributions support webhooks (marked green).
Related Activity | Event | Notify customers about promotion | Send and publish unique codes from campaign | Send plain message to customers |
Segment | Customer entered segment | |
|
|
Segment | Customer left segment | |
|
|
Cart | Order update | |
|
|
Cart | Order has been paid | |
|
|
Cart | Order creation | |
|
|
Cart | Order cancelled | |
|
|
Voucher | Gift credits added | |
|
|
Voucher | Loyalty points added | |
|
|
Voucher | Voucher redeemed | |
|
|
Voucher | Voucher redemption rollback | |
|
|
Customer rewards | Reward redemption | |
|
|
Customer | Custom event | |
|
|
One or bulk messages | Manual message | |
|
|
All campaigns with codes | Successfully published | |
|
|
Get notified when a webhook does not reach the destination
You can set up a notification in the Notification Center > Account Settings to inform you via Email or in the App that a webhook did not reach the destination.
Distribution Manager
In the last step of the Distribution Manager, you need to choose message channels. At that point, you can choose WEBHOOK.
Enter a name for the event and the target URL. Then customize the type of information to include in the webhook notification.
Loyalty program
Loyalty campaign notifications are configured when creating a loyalty campaign in the Campaign Manager. The webhook notifications are invoked by the following actions:
- Publication (assigning) a loyalty card to a customer
- New points on the loyalty card
- Reward redemption and updated points balance
Read more about configuring loyalty program notifications here.
Referral program
Referral campaign level webhook notifications can be configured in the Referral Campaign Manager. There are two types of notifications that can be delivered using webhooks:
- When new referral code is published to a referrer
- when the referrer becomes eligible to receive a reward.
Read more about configuring referral program notifications. The configuration is described in this tutorial. You can configure a webhook notification for the referrer and the referee.
Responding to a webhook
Voucherify expects your webhook to return a response with a `2XX` HTTP status code, indicating that the webhook has been received successfully. If a webhook is not successfully received for any reason, Voucherify will continue trying to send the webhook in intervals of 1 minute, 2 minutes, 4 minutes, 8 minutes, 16 minutes, 32 minutes and continues at less frequent intervals until a final re-try at 24 hours.
Re-try No. | Time since initial attempt | Interval to next re-try |
1 | 1 min | 1 min |
2 | 2 min | 2 min |
3 | 4 min | 4 min |
4 | 8 min | 8 min |
5 | 16 min | 16 min |
6 | 32 min | 32 min |
7 | 1 h 4 m | 1 h 4 m |
8 | 2 h 8 m | 2 h 8 m |
9 | 4 h 16 m | 4 h 16 m |
10 | 8 h 32 m | 8 h 32 m |
11 | 17 h 4 m | 6 h 56 m |
12 | 24 h | Final re-try |
Latency
Your endpoint must return a response in under 10 seconds, otherwise it will be considered as an error.
What happens after the 12th try?
- Project level webhooks that are setup in Project Settings > General > Webhooks are disabled after 12 unsuccessful tries
- distribution-based webhooks that are set up as channels in the Distributions manager are paused after 12 unsuccessful tries
Re-enabling a webhook
Project-level webhook
To re-enable a disabled webhook, you need to go into Project Settings > General > Webhooks, edit the specific Webhook and click Update endpoint.
Distribution based webhook
To re-enable a paused webhook, you need to go into the Distribution Manager, click on the specific distribution that has been paused, and click on the set live icon in the upper right hand corner.
Authentication
Once your server is configured to receive payloads, it will listen for any payload sent to the endpoint you configured. For security reasons, you probably want to limit requests to those coming from Voucherify. To do so, you should copy a secret token and validate the information.
You can generate a secret key in the Project Settings:
Each webhook sent from Voucherify will contain the signature of the webhook in the header field:
x-voucherify-signature
.
Then, you can validate the signature by reconstructing it and comparing it to the one sent in the webhook header field.
You can reconstruct it using the keyed-hash message authentication code HMAC, which is built using the cryptographic hash function sha256 and the secret cryptographic key taken from the project settings.
To see an example, go to the verifySignature
method in the NodeJS SDK
const crypto = require('crypto') verifySignature: function (signature, message, secretKey) { return crypto.createHmac('sha256', secretKey) .update(isString(message) && message || JSON.stringify(message)) .digest('hex') === signature }
IP Whitelisting
When Voucherify sends a webhook, the Voucherify servers make network requests to our tenants’ or third parties’ servers.
For adding an additional layer of security, you can do IP whitelisting. That mechanism will verify that webhook requests are coming from Voucherify.
Voucherify sends webhooks from the IP ranges below.
Instance | IP |
eu1 | 34.247.197.22 |
us1 | 100.25.106.67 |
as1 | 52.76.98.82 |