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.

New webhooks (v2024-01-01) have been introduced in v20231205. The payload of the v2024-01-01 webhooks is significantly different from v2018-01-01 webhooks. However, all the events listed in the Project settings for the v2018-08-01 webhooks are available for v2024-01-01 webhooks.

Contents:

  1. Project-based notifications
  2. Distribution channel
  3. Loyalty program
  4. Referral program
  5. Responding to a webhook
  6. Re-enabling a webhook
  7. Authentication
  8. 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, 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 and choose the webhooks version you would like to use.

If your account has been created after the v20231205 release, you can only use the new webhooks.

After selecting the appropriate version, you can:

  • Call a webhook for every listed event
  • Call a webhook for a specific event or a subset of events

When you are finished configuring the webhook, confirm the settings with the  Create endpoint.

From now on, when Voucherify logs 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 the 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.

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. 

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.


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 a 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 the 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 an error.

What happens after the 12th try?

  • Project-level webhooks that are set 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:

  1. In the Project Settings, go to the General tab.
  2. Scroll down to the Webhooks section.
  3. Edit the specific Webhook.
  4. Click Is active.
  5. 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:

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.

To add 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
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us