Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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"
  }
}