Webhooks v2024-01-01

The v2024-01-01 webhook version can be used to inform your system about various events that are triggered in Voucherify. The v2024-01-01 webhooks work for distributions and events listed in the Project settings.

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

  1. In Voucherify dashboard, go to Project settings.
  2. Scroll down to the Webhooks section.
  3. Click the plus button – Add new webhook.
  4. Choose v2024-01-01 webhook version.
  5. 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.
  6. 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 attemptInterval to next re-try
11 min1 min
22 min2 min
34 min4 min
48 min8 min
516 min16 min
632 min32 min
71 h 4 min1 h 4 min
82 h 8 min2 h 8 min
94 h 16 min4 h 16 min
108 h 32 min8 h 32 min
1117 h 4 min17 h 4 min
1224 hFinal 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 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:

  1. Go to the Distribution Manager.
  2. Click the distribution that has been paused.
  3. 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.

InstanceIP
eu134.247.197.22
63.32.191.141 (new)
52.215.148.84 (new)
us1100.25.106.67
18.209.236.215 (new)
34.192.255.99 (new)
as152.76.98.82
54.169.8.101 (new)
13.214.87.160 (new)

🚧

New Addresses

The new addresses are not live yet. The actual traffic will begin on 18th October.

Webhooks Available in Project Settings

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

The following events can send a webhook:

Project Setting Webhook Payload

AttributesDescription
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.updated, campaign.promotion_tier.created, campaign.promotion_tier.deleted, campaign.promotion_tier.disabled, campaign.promotion_tier.enabled, campaign.promotion_tier.updated, campaign.vouchers.generation.completed, 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.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:

source
object

Contains details about the source of the webhook sendout.

AttributesDescription
id
string

ID number of the webhook.

Example:

wh_j56Vfy47Vx9YOX7QYD1fzHnc

object
string

Determines the type of the object.

Available values: webhook Example:

webhook

target_url
string

The address where the webhook will be sent.

event
object

Contains other data of the event that triggered the sendout.

AttributesDescription
id
string

Unique identifier of the event that triggered the sendout.

Example:

evred_1f3611301g3127begb

type
string

Determines the type of the event.

Example:

redemption.succeeded

created_at
string

The exact moment when the event was created.

Example:

2024-01-01T11:11:11.111Z

entity_id
string

Unique identifier of the entity that triggered the sendout.

Example:

r_1f3611302bf107befb

group_id
string

Unique identifier of the request that triggered the event.

Example:

v-1f36113948e50fc4ge

event_source
object

Contains the source of the object that triggered the sendout.

AttributesDescription
channel
string

Determines the channel that triggered the sendout.

Available values: USER_PORTAL, API, CLIENT_API, INTERNAL
Example:

API

user
string

Defines the user who triggered the event.

api_key
object

Determines the API key used to initiate the sendout.

AttributesDescription
name
string

Channel name in the application keys.

app_id
string

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

📘

Distribution Webhooks

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.

Campaign Distributions – Notifications

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

Distribution Webhook Payload

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

source
object

Contains details about the source of the webhook sendout.

AttributesDescription
id
string

Unique identifier of the distribution that sent the webhook.

Example:

distr_TrJj0lHV44EMt6HvLa2pyNlHTF

object
string

Determines the type of the object.

Available values: distribution
Example:

distribution

target_url
string

The address where the webhook is be sent.

event
object

Contains other data of the event that triggered the sendout.

AttributesDescription
id
string

Unique identifier of the event that triggered the sendout.

Example:

evred_1f3611301g3127begb

type
string

Determines the type of the event.

Example:

customer.custom_event

customer.entered.segment

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.reward_redemptions.completed

customer.segment.entered

customer.segment.left

customer.voucher.gift.balance_added

customer.voucher.loyalty_card.points_added

customer.voucher.loyalty_card.points_expired

manual_distribution_schedule

created_at
string

The exact moment when the event was created.

Example:

2024-01-01T11:11:11.111Z

entity_id
string

Unique identifier of the entity that triggered the sendout.

Example:

r_1f3611302bf107befb

group_id
string

Unique identifier of the request that triggered the event.

Example:

v-1f36113948e50fc4ge

event_source
object

Contains the source of the object that triggered the sendout.

AttributesDescription
channel
string

Determines the channel that triggered the sendout.

Available values: USER_PORTAL, API, CLIENT_API, INTERNAL
Example:

API

user
string

Defines the user who triggered the event.

api_key
object

Determines the API key used to initiate the sendout.

AttributesDescription
name
string

Channel name in the application keys.

app_id
string

Contains the application ID from the Voucherify API key pair.

Example:

1XXXX5XX-0XXX-XXXb-X7XX-XX2XXaXXX6XX