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

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

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.

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.