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:

  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, 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.

Create webhook

Start off by providing a target URL.

Configure webhook

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.

Update webhook

Delete an Endpoint

Click on the trash can icon and click Delete.

Delete webhook


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. 

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:

Generate secret key

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
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