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

# Setup webhooks

> Learn how to set up webhooks in Masivo to receive notifications about events, rewards, and more

## 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](/api-reference/guides/setup-webhooks/#masivo-webhook-events) 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.

<Note>
  The URL must follow the HTTPS protocol. Masivo will send a **POST request** to
  this URL with the event payload.
</Note>

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.

<Note>Migrated customers will not trigger this event</Note>

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

<Note>
  This webhook event may be sent multiple times as Masivo retries failed events.
</Note>

```json theme={null}
{
  "event": "BEHAVIOR_EVENT_FAILED",
  "data": {
    "customer_id": "<YOUR_CUSTOMER_ID>",
    // The failed behavior event
    "event": {...}
  }
}
```

### Coupon redemption

Triggers when a customer redeems a coupon.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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"
  }
}
```