Webhooks v2024-01-01

The v2024-01-01 webhooks (both for distributions and project settings) share the same data structure, consisting of the following keys:

id
project_id
created_at
type
data
source
event

The values for the type and data depend on the event that triggers the webhook. Go to Project Setting Webhook Payload and Distribution Webhook Payload to learn more about their payloads.

Configuring v2024-01-01 Webhooks

In Voucherify dashboard, go to Project settings.
Scroll down to the Webhooks section.
Click the plus button – Add new webhook.
Choose v2024-01-01 webhook version.
Provide the following details:
1. Enter the target URL.
2. Tick the Is active? checkbox.
3. Select the events you want to receive. If you want to receive all the events, choose Send me all events option.
4. Click Send test webhook to test your configuration (optional).
5. Click Create endpoint.
If necessary for authentication reasons, enter the Secret key in your system to receive webhooks from Voucherify.

You can add multiple webhooks to your projects following the steps above. To update webhook details, click the Pencil button – edit. Enter your changes and click Update endpoint. To delete a webhook, click the Trash button and click Delete.

Get Notified About Failed Sendouts

You can set up notifications to inform you via email or in the app that a webhook did not reach the destination. Go to the Notification Center > Account Settings and scroll down to Webhook callout notifications to configure notifications.

Audit log

You can check details about a webhook sendout. In Voucherify dashboard, go to Audit log and Webhook sendouts tab. The Audit Log includes the following details:

Webhook status
Webhook type
Webhook ID
Source
Target URL
Request ID
Event created at
Executed at
Complete webhook data (three dot menu on the right > Show data)

You can also send a failed webhook again. Go to the three dot menu on the right > Retry.

Responding to Webhooks

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 the following intervals:

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 min	1 h 4 min
8	2 h 8 min	2 h 8 min
9	4 h 16 min	4 h 16 min
10	8 h 32 min	8 h 32 min
11	17 h 4 min	17 h 4 min
12	24 h	Final re-try

Your endpoint must return a response in under 10 seconds; otherwise, it will be considered an error.

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

In the Project Settings, go to the General tab.
Scroll down to the Webhooks section.
Edit the specific Webhook.
Click Is active.
Click Update endpoint.

Distribution-Based Webhook

To re-enable a paused webhook:

Go to the Distribution Manager.
Click the distribution that has been paused.
Click the set live icon in the upper right 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 may 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 in the Webhooks section. Each webhook sent from Voucherify contains the x-voucherify-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. Reconstruct it using the keyed-hash message authentication code HMAC. It is built with the cryptographic hash function sha256 and the secret cryptographic key taken from the Project settings. See the following examples for Java and the verifySignature method in the NodeJS SDK.

import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

class HelloWorld {

    public static void main(String[] args)  throws InvalidKeyException, NoSuchAlgorithmException {
        byte[] secretKey = "secretKey".getBytes(StandardCharsets.UTF_8);

        // when payload is JSON object - whitespaces must be removed
        String signature1 = "a17d2ac229d1ebbb5f10e839c7985c4818e5986eab297f7e5979196d4d7d3ed2";
        System.out.println(verifySignature(removeWhitespaces("{\n  \"a\": 1\n}"), signature1, secretKey));
        System.out.println(verifySignature(removeWhitespaces("{\"a\":1}"), signature1, secretKey));

        String signature2 = "f7cf97814a03146abedb9793f56e1dec34f618f82d10395310d053f749483ffb";
        System.out.println(verifySignature(removeWhitespaces("{\n  \"a\\\"b\": 1\n}"), signature2, secretKey));

        // when payload is directly a String
        String signature3 = "53ff92957e1427ce23ad5bda9d0c5f2f4ff384d0806b83eeacb510c842d3a358";
        System.out.println(verifySignature("  message  ", signature3, secretKey));
    }
    
    public static String removeWhitespaces(String json) {
        boolean quoted = false;
        boolean escaped = false;
        String out = "";
    
        for (Character c : json.toCharArray()) {
            if (escaped) {
                out += c;
                escaped = false;
                continue;
            }
    
            if (c == '"') {
                quoted = !quoted;
            } else if (c == '\\') {
                escaped = true;
            }
    
            if (Character.isWhitespace(c) &! quoted) {
                continue;
            }
    
            out += c;
        }

        return out;
    }
    
    public static boolean verifySignature(String payload, String signature, byte[] secretKey) throws InvalidKeyException, NoSuchAlgorithmException {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secretKey, "HmacSHA256"));
        byte[] hash = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
        String generatedSignature = bytesToHex(hash);
        return generatedSignature.equals(signature);
    }
    
    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder(bytes.length * 2);
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }

}

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 tenants’ or third parties’ servers. To add an additional layer of security, you can do IP whitelisting. This mechanism verifies if webhook requests come from Voucherify. Voucherify sends webhooks from the IP ranges below. Add all three addressses for your instance.

Instance	IP
eu1	34.247.197.2263.32.191.14152.215.148.84
us1	100.25.106.6718.209.236.21534.192.255.99
as1	52.76.98.8254.169.8.10113.214.87.160

Webhooks Available in Project Settings

These webhooks are triggered by the events listed in the Project settings.

Documentation of some of the events is still in progress.

The following events can send a webhook:

Redemption events:
Publication event:
- Publication succeeded
Customer events:
- Customer created
- Customer deleted
- Customer rewarded
- Customer rewarded loyalty points
- Customer confirmed
Voucher events:
Campaign events:
- Campaign created
- Campaign voucher generation completed
- Campaign disabled
- Campaign enabled
- Campaign updated
- Campaign deleted
- Campaign vouchers added
Promotion tier events:
Business validation rule events:
Earning rule events:
- Earning rule assigned
- Earning rule deleted
- Earning rule disabled
- Earning rule enabled
- Earning rule updated
Loyalty tier related events:
Promotion stack events:
- Promotion stack created
- Promotion stack updated
Referral tier related events:
- Referral tier created
- Referral tier deleted
- Referral tier updated
Reward assignment events:
- Reward assignment created
- Reward assignment deleted
- Reward assignment updated
Voucher generation events:
- Voucher generation failed
- Voucher generation started

Documentation for some events is in progress. Updates will be provided soon.

Project Setting Webhook Payload

Attributes	Description
id`string`	Unique identifier of the sendout for this webhook.Example:whs_0e16e42bc6e0c65b57
project_id`string`	Unique identifier of the Voucherify project.Example:proj_5T4Rpl4T1nuM
created_at`string`	The exact moment when the webhook was created.Example:2024-01-01T11:11:11.111Z
type`string`	Name of the event that triggerered the webhook sendout.Available values: `business_validation_rule.assignment.created`, `business_validation_rule.assignment.deleted`, `business_validation_rule.created`, `business_validation_rule.deleted`, `business_validation_rule.updated`, `campaign.created`, `campaign.deleted`, `campaign.disabled`, `campaign.enabled`, `campaign.earning_rule.assigned`, `campaign.earning_rule.deleted`, `campaign.earning_rule.disabled`, `campaign.earning_rule.enabled`, `campaign.earning_rule.updated`, `campaign.loyalty_tier.created`, `campaign.loyalty_tier.deleted`, `campaign.loyalty_tier.updated`, `campaign.promotion_stack.created`, `campaign.promotion_stack.updated`, `campaign.promotion_tier.created`, `campaign.promotion_tier.deleted`, `campaign.promotion_tier.disabled`, `campaign.promotion_tier.enabled`, `campaign.promotion_tier.updated`, `campaign.referral_tier.created`, `campaign.referral_tier.deleted`, `campaign.referral_tier.updated`, `campaign.reward.assignment.created`, `campaign.reward.assignment.deleted`, `campaign.reward.assignment.updated`, `campaign.updated`, `campaign.vouchers.added`, `campaign.vouchers.generation.completed`, `campaign.vouchers.generation.failed`, `campaign.vouchers.generation.started`, `customer.confirmed`, `customer.created`, `customer.deleted`, `customer.rewarded`, `customer.rewarded.loyalty_points`, `publication.succeeded`, `redemption.failed`, `redemption.rollback.failed`, `redemption.rollback.succeeded`, `redemption.succeeded`, `voucher.created`, `voucher.deleted`, `voucher.disabled`, `voucher.enabled`, `voucher.gift.balance_added`, `voucher.gift.transaction.created`, `voucher.loyalty_card.pending_points.activated`, `voucher.loyalty_card.pending_points.added`, `voucher.loyalty_card.pending_points.canceled`, `voucher.loyalty_card.pending_points.updated`, `voucher.loyalty_card.points_added`, `voucher.loyalty_card.points_expired`, `voucher.loyalty_card.transaction.created`, `voucher.published`, `voucher.updated`
data`object`	Payload depends on the event that triggered the webhook sendout. Project settings cover the following events:- - `business_validation_rule.assignment.created`

business_validation_rule.assignment.deleted
business_validation_rule.created
business_validation_rule.deleted
business_validation_rule.updated
campaign.created
campaign.deleted
campaign.disabled
campaign.enabled
campaign.updated
campaign.earning_rule.assigned
campaign.earning_rule.deleted
campaign.earning_rule.disabled
campaign.earning_rule.enabled
campaign.earning_rule.updated
campaign.loyalty_tier.created
campaign.loyalty_tier.deleted
campaign.loyalty_tier.updated
campaign.promotion_tier.created
campaign.promotion_tier.deleted
campaign.promotion_tier.disabled
campaign.promotion_tier.enabled
campaign.promotion_tier.updated
campaign.promotion_stack.created
campaign.promotion_stack.updated
campaign.referral_tier.created
campaign.referral_tier.deleted
campaign.referral_tier.updated
campaign.reward.assignment.created
campaign.reward.assignment.deleted
campaign.reward.assignment.updated
campaign.vouchers.generation.completed
campaign.vouchers.generation.failed
campaign.vouchers.generation.started
campaign.vouchers.added
customer.created
customer.deleted
customer.confirmed
customer.rewarded
customer.rewarded.loyalty_points
publication.succeeded
redemption.failed
redemption.rollback.failed
redemption.rollback.succeeded
redemption.succeeded
voucher.created
voucher.deleted
voucher.disabled
voucher.enabled
voucher.gift.balance_added
voucher.gift.transaction.created
voucher.loyalty_card.pending_points.activated
voucher.loyalty_card.pending_points.added
voucher.loyalty_card.pending_points.canceled
voucher.loyalty_card.pending_points.updated
voucher.loyalty_card.points_added
voucher.loyalty_card.points_expired
voucher.loyalty_card.transaction.created
voucher.published
voucher.updated | | sourceobject | Contains details about the source of the webhook sendout.Attributes Descriptionidstring ID number of the webhook. Example: wh_j56Vfy47Vx9YOX7QYD1fzHnc objectstring Determines the type of the object. Available values: webhook Example: webhook target_urlstring The address where the webhook will be sent. | | eventobject | Contains other data of the event that triggered the sendout.Attributes Descriptionidstring Unique identifier of the event that triggered the sendout. Example: evred_1f3611301g3127begb typestring Determines the type of the event. Example: redemption.succeeded created_atstring The exact moment when the event was created. Example: 2024-01-01T11:11:11.111Z entity_idstring Unique identifier of the entity that triggered the sendout. Example: r_1f3611302bf107befb group_idstring Unique identifier of the request that triggered the event. Example: v-1f36113948e50fc4ge event_sourceobject Contains the source of the object that triggered the sendout. Attributes Descriptionchannelstring Determines the channel that triggered the sendout. Available values: USER_PORTAL, API, CLIENT_API, INTERNAL Example: API userstring Defines the user who triggered the event. api_keyobject Determines the API key used to initiate the sendout. Attributes Descriptionnamestring Channel name in the application keys. app_idstring Contains the application ID from the Voucherify API key pair. Example: 1XXXX5XX-0XXX-XXXb-X7XX-XX2XXaXXX6XX |

Webhooks Available in Distributions

These webhooks are triggered by the events which cause distribution. Some distribution events, e.g. Customer entered segment, have different purposes:

Notify customers about promotion
Send and publish unique codes from campaign
Send plain message to customers

Learn more about configuring distribution webhooks from the Webhook distributions article.

The documentation of these events contains data for all purposes. The objects which are shared between the purposes are marked as required. The objects which appear only for specific purposes are respectively described.

Custom events:
- Custom event
Segment related activities:
- Customer entered segment
- Customer left segment
Manual messages:
- Notify customers about promotion – covered by the MANUAL_DISTRIBUTION_SCHEDULE event
- Send and publish unique codes from a campaign – covered by the MANUAL_DISTRIBUTION_SCHEDULE event
- Send a plain message to customers – does not support webhooks as a distribution channel
Cart related activities:
Publishing codes:
- Successfully published
Voucher related activities:
Customer rewards:
- Reward redeemed
Loyalty tier related activities:
Referral related activities:
- Customer was referred

Campaign Distributions – Notifications

The following campaigns can also trigger webhook sendouts as a distribution:

Loyalty campaigns:
Referral campaigns:
- Send referral code to the referrer
- Customer referred (documentation in progress)

Distribution Webhook Payload

Attributes	Description
id`string`	Unique identifier of the sendout for this webhook.Example:whs_0e16e42bc6e0c65b57
project_id`string`	Unique identifier of the Voucherify project.Example:proj_5T4Rpl4T1nuM
created_at`string`	The exact moment when the webhook was created.Example:2024-01-01T11:11:11.111Z
type`string`	Displays the name entered in the `Event name` field in the distribution creator.
data`object`	Payload depends on the event that triggered the webhook sendout. Distributions cover the following events:- `customer.custom_event`

customer.loyalty.tier.downgraded
customer.loyalty.tier.joined
customer.loyalty.tier.left
customer.loyalty.tier.prolonged
customer.loyalty.tier.upgraded
customer.order.canceled
customer.order.created
customer.order.paid
customer.order.updated
customer.publication.succeeded
customer.redemption.rollback.succeeded
customer.redemption.succeeded
customer.referred
customer.reward_redemptions.completed
customer.rewarded
customer.rewarded.loyalty_points
customer.segment.entered
customer.segment.left
customer.voucher.gift.balance_added
customer.voucher.loyalty_card.pending_points.activated
customer.voucher.loyalty_card.pending_points.added
customer.voucher.loyalty_card.pending_points.canceled
customer.voucher.loyalty_card.pending_points.updated
customer.voucher.loyalty_card.points_added
customer.voucher.loyalty_card.points_expired
manual_distribution_schedule | | sourceobject | Contains details about the source of the webhook sendout.Attributes Descriptionidstring Unique identifier of the distribution that sent the webhook. Example: distr_TrJj0lHV44EMt6HvLa2pyNlHTF objectstring Determines the type of the object. Available values: distribution Example: distribution target_urlstring The address where the webhook is be sent. | | eventobject | Contains other data of the event that triggered the sendout.Attributes Descriptionidstring Unique identifier of the event that triggered the sendout. Example: evred_1f3611301g3127begb typestring Determines the type of the event. Example: customer.custom_event customer.loyalty.tier.downgraded customer.loyalty.tier.joined customer.loyalty.tier.leftd customer.loyalty.tier.prolonged customer.loyalty.tier.upgraded customer.order.canceled customer.order.created customer.order.paid customer.order.updated customer.publication.succeeded customer.redemption.rollback.succeeded customer.redemption.succeeded customer.referred customer.reward_redemptions.completed customer.rewarded customer.rewarded.loyalty_points customer.segment.entered customer.segment.left customer.voucher.gift.balance_added customer.voucher.loyalty_card.pending_points.activated customer.voucher.loyalty_card.pending_points.added customer.voucher.loyalty_card.pending_points.canceled customer.voucher.loyalty_card.points_added customer.voucher.loyalty_card.points_expired loyalty_card.pending_points.updated manual_distribution_schedule created_atstring The exact moment when the event was created. Example: 2024-01-01T11:11:11.111Z entity_idstring Unique identifier of the entity that triggered the sendout. Example: r_1f3611302bf107befb group_idstring Unique identifier of the request that triggered the event. Example: v-1f36113948e50fc4ge event_sourceobject Contains the source of the object that triggered the sendout. Attributes Descriptionchannelstring Determines the channel that triggered the sendout. Available values: USER_PORTAL, API, CLIENT_API, INTERNAL Example: API userstring Defines the user who triggered the event. api_keyobject Determines the API key used to initiate the sendout. Attributes Descriptionnamestring Channel name in the application keys. app_idstring Contains the application ID from the Voucherify API key pair. Example: 1XXXX5XX-0XXX-XXXb-X7XX-XX2XXaXXX6XX |

Getting started

Integration Blueprint

Development

Campaigns Recipes

Discounts Recipes

Distributions Recipes

More

Configuring v2024-01-01 Webhooks

Get Notified About Failed Sendouts

Audit log

Responding to Webhooks

Re-Enabling a Webhook

Project-Level Webhook

Distribution-Based Webhook

Authentication

IP Whitelisting

Webhooks Available in Project Settings

Project Setting Webhook Payload

Webhooks Available in Distributions

Campaign Distributions – Notifications

Distribution Webhook Payload

​Configuring v2024-01-01 Webhooks

​Get Notified About Failed Sendouts

​Audit log

​Responding to Webhooks

​Re-Enabling a Webhook

​Project-Level Webhook

​Distribution-Based Webhook

​Authentication

​IP Whitelisting

​Webhooks Available in Project Settings

​Project Setting Webhook Payload

​Webhooks Available in Distributions

​Campaign Distributions – Notifications

​Distribution Webhook Payload

Configuring v2024-01-01 Webhooks

Get Notified About Failed Sendouts

Audit log

Responding to Webhooks

Re-Enabling a Webhook

Project-Level Webhook

Distribution-Based Webhook

Authentication

IP Whitelisting

Webhooks Available in Project Settings

Project Setting Webhook Payload

Webhooks Available in Distributions

Campaign Distributions – Notifications

Distribution Webhook Payload