Setup webhooks

What are webhooks?

Webhooks enable real-time communication between servers. They allow one application to automatically send data to another whenever a specific event occurs.

Webhooks in Masivo

Masivo allows you to set up webhooks to receive notifications about several events including:

Rewards accumulations & redemptions
Customer registrations
Event fulfillments & failures
Coupon redemptions
Tier upgrades & downgrades

Check our full list of events and their payloads

Setting up webhooks in Masivo

To set up webhooks in Masivo, first navigate to the Settings section in the dashboard. You can find it in the left sidebar. Then click on the Webhooks menu. Now, click on the Add new webhook button. You will be prompted to enter the URL where you want to receive the notifications.

The URL must follow the HTTPS protocol. Masivo will send a POST request to this URL with the event payload.

Finally, select the events you want to receive notifications for. You can choose from the list of available events. Then click on the Save button. You can setup multiple webhooks to receive notifications for different events. Is up to you to decide which events you want to receive in each webhook.

Masivo webhook events

Registration

Triggers when a new customer is registered to your program.

Migrated customers will not trigger this event

{
  "event": "CUSTOMER_REGISTRATION",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // Customer data
    "customer": {...},
    // Customer's wallet
    "wallet": {...}
  }
}

Reward accumulation

Triggers when a customer accumulates any type of reward. This includes when a behavior event is fulfilled or when a coupon is redeemed.

{
  "event": "CUSTOMER_ACCUMULATION",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // List of accumulated reward lines
    "lines": [...],
    // The updated wallet
    "wallet": {...}
  }
}

Reward redemption

Triggers when a customer redeems any type of reward. Most commonly, this event is triggered when a customer redeem rewards in a PURCHASE behavior event.

{
  "event": "CUSTOMER_REDEMPTION",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // List of redeemed reward lines
    "lines": [...],
    // The updated wallet
    "wallet": {...}
  }
}

Reward reservation

Triggers when a customer reserves a reward. This event is triggered when a PURCHASE behavior event is set with fulfilled: false.

{
  "event": "REWARDS_RESERVATION",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // List of reserved reward lines
    "lines": [...],
    // The updated wallet
    "wallet": {...}
  }
}

Reward reservation cancelled

Triggers when a behavior event is cancelled before it was fulfilled. The event will notify the new state of the customer wallet along the released lines.

{
  "event": "REWARDS_RESERVATION_CANCELLED",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // List of released reward lines
    "lines": [...],
    // The updated wallet
    "wallet": {...}
  }
}

Behavior event fulfilled

Triggers when a behavior event is fulfilled.

{
  "event": "BEHAVIOR_EVENT_FULFILLED",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // The fulfilled behavior event
    "event": {...}
  }
}

Behavior event failed

Triggers when a behavior event fails to complete.

This webhook event may be sent multiple times as Masivo retries failed events.

{
  "event": "BEHAVIOR_EVENT_FAILED",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // The failed behavior event
    "event": {...}
  }
}

Coupon redemption

Triggers when a customer redeems a coupon.

{
  "event": "COUPON_REDEMPTION",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // The id of the campaign where the coupon was redeemed
    "campaign_id": "<YOUR_CAMPAIGN_ID>",
    // The redeemed coupon code
    "code": "<COUPON-CODE>"
  }
}

Tier upgrade

Triggers when a customer’s tier is upgraded. This can happen when a customer accumulates enough points or meets the entry requirements for a higher tier.

{
  "event": "TIER_UPGRADE",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // The tier ID the customer was upgraded from
    "from_tier_id": "<TIER_ID>",
    // The tier ID the customer was upgraded to
    "to_tier_id": "<TIER_ID>",
    // The name of the tier the customer was upgraded from
    "from_tier_name": "Silver",
    // The name of the tier the customer was upgraded to
    "to_tier_name": "Gold",
    // The level of the tier the customer was upgraded from
    "from_tier_level": 1,
    // The level of the tier the customer was upgraded to
    "to_tier_level": 2,
    // What triggered the tier change
    "triggered_by": "EVENT", // or "CRON_DOWNGRADE" or "REVERSAL"
    // Optional: The event ID that triggered the tier change (if triggered_by is "EVENT" or "REVERSAL")
    "trigger_event_id": "<EVENT_ID>",
    // Optional: The event type that triggered the tier change (if triggered_by is "EVENT" or "REVERSAL")
    "trigger_event_type": "PURCHASE"
  }
}

Tier downgrade

Triggers when a customer’s tier is downgraded. This can happen during the cron job when a customer no longer meets the requirements to maintain their current tier, or when an event is reversed.

{
  "event": "TIER_DOWNGRADE",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // The tier ID the customer was downgraded from
    "from_tier_id": "<TIER_ID>",
    // The tier ID the customer was downgraded to
    "to_tier_id": "<TIER_ID>",
    // The name of the tier the customer was downgraded from
    "from_tier_name": "Gold",
    // The name of the tier the customer was downgraded to
    "to_tier_name": "Silver",
    // The level of the tier the customer was downgraded from
    "from_tier_level": 2,
    // The level of the tier the customer was downgraded to
    "to_tier_level": 1,
    // What triggered the tier change
    "triggered_by": "CRON_DOWNGRADE", // or "EVENT" or "REVERSAL"
    // Optional: The event ID that triggered the tier change (if triggered_by is "EVENT" or "REVERSAL")
    "trigger_event_id": "<EVENT_ID>",
    // Optional: The event type that triggered the tier change (if triggered_by is "EVENT" or "REVERSAL")
    "trigger_event_type": "REVERSE"
  }
}

Registration flow — CUSTOMER_REGISTRATION and profile lifecycle notifications
Activity & events — Reward, tier, and accumulation webhooks from the loyalty path

API Documentation

Endpoints

Guides

Resources

Setup webhooks

What are webhooks?

Webhooks in Masivo

Setting up webhooks in Masivo

Masivo webhook events

Registration

Reward accumulation

Reward redemption

Reward reservation

Reward reservation cancelled

Behavior event fulfilled

Behavior event failed

Coupon redemption

Tier upgrade

Tier downgrade

​What are webhooks?

​Webhooks in Masivo

​Setting up webhooks in Masivo

​Masivo webhook events

​Registration

​Reward accumulation

​Reward redemption

​Reward reservation

​Reward reservation cancelled

​Behavior event fulfilled

​Behavior event failed

​Coupon redemption

​Tier upgrade

​Tier downgrade

​Related architecture

What are webhooks?

Webhooks in Masivo

Setting up webhooks in Masivo

Masivo webhook events

Registration

Reward accumulation

Reward redemption

Reward reservation

Reward reservation cancelled

Behavior event fulfilled

Behavior event failed

Coupon redemption

Tier upgrade

Tier downgrade

Related architecture