# Webhooks

Upzelo uses webhooks to notify your application when an event happens on your Upzelo account. Webhooks are useful for you to take any action needed for asynchronous events like when a customer cancels their subscription or accepts a discount offer.

## How Upzelo uses webhooks

Webhooks enable Upzelo to push real-time notifications to your app. We send you a JSON payload to a URL that has been specified in your webhook configuration. You can then use these notifications to execute actions on your own platform.

### How to receive webhooks

1. Create a new webhook in the [Upzelo developer dashboard](https://www.upzelo.com/app/developer/webhooks)
2. Create an endpoint on your web app to listen for the webhooks
3. Handle the request by parsing the payload and returning a 200 response code.

## When are webhooks sent?

Webhooks are sent within seconds of an event happening on Upzelo.

Upzelo uses exponential backoffs when sending webhooks. What this means is that the time between retries will increase until we hit a maximum limit, or a `200` status code is returned. Below is a table outlining the times between attempts.

| Attempt Number | Delay (minutes) |
| -------------- | --------------- |
| 1              | Immediately     |
| 2              | 3               |
| 3              | 5               |
| 4              | 9               |
| 5              | 17              |
| 6              | 33              |
| 7              | 65              |

## What events are available?

* Flow Started - This is when a customer begins a flow via Upzelo.
* Flow Abandoned - This is when a flow is started, but not completed after 60 minutes.
* Subscription Pause - When a customer accepts a pause offer.
* Subscription Skip Charge - When a customer accepts a skip charge offer.
* Subscription Plan Change - When a customer accepts a plan change offer.
* Subscription Free Period - When a customer accepts a free period offer.
* Subscription Discount - When a customer accepts a discount offer.
* Subscription Cancelled - When a customer cancels their subscription.
* New Request - When a new request enters the system from a Flow

## Example event payloads

### Flow

{% tabs %}
{% tab title="Flow Started" %}

```json
{
    "data": {
        "type": "flow.started",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "flow": {
            "title": "High-value customers",
            "reason": "Matched audience"
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
    }
}
```

{% endtab %}

{% tab title="Flow Abandoned" %}

```json
{
    "data": {
        "type": "flow.abandoned",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "flow": {
            "title": "High-value customers",
            "reason": "Matched audience"
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
    }
}
```

{% endtab %}
{% endtabs %}

### Subscription

{% tabs %}
{% tab title="Pause" %}

```json
{
    "data": {
        "type": "subscription.pause",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "duration": 2,
        "duration_unit": "month",
        "app_id": "upz_app_1234",
        "test_mode": true,
    }
}
```

{% endtab %}

{% tab title="Skip Charge" %}

```json
{
    "data": {
        "type": "subscription.skip-charge",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
        }
    }
}
```

{% endtab %}

{% tab title="Plan Change" %}

```json
{
    "data": {
        "type": "subscription.plan-change",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "price": {
            "external_id": "price_1234"
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
    }
}
```

{% endtab %}

{% tab title="Free Period" %}

```json
{
    "data": {
        "type": "subscription.free-period",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "coupon": {
            "external_id": "coupon_1234",
            "duration_in_months": 1,
            "duration": "once",
            "amount_off": null,
            "percent_off": 20
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
    }
}
```

{% endtab %}

{% tab title="Discount" %}

```json
{
    "data": {
        "type": "subscription.discount",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "coupon": {
            "external_id": "coupon_1234",
            "duration_in_months": 1,
            "duration": "once",
            "amount_off": 1000, // Cent value
            "percent_off": null
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
    }
}
```

{% endtab %}

{% tab title="Cancel" %}

```json
{
    "data": {
        "type": "subscription.cancelled",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
    }
}
```

{% endtab %}
{% endtabs %}

### Requests

{% tabs %}
{% tab title="New Request" %}

```json
{
    "data": {
        "type": "request.created",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "richard@piedpiper.com",
            "description": "Created middle-out compression",
            "created": "2023-01-01 00:02:04",
            "phone": "07123456789",
            "additional_id": null,
            "upzelo_id": "upz_cus_1234",
            "metadata": null,
            "country": "GB",
            "state": "East Sussex"
        },
        "subscription": {
            "external_id": "sub_1234",
            "additional_id": null,
            "current_period_start": "2023-01-01 00:00:00",
            "current_period_end": "2023-01-31 23:59:59",
            "cancel_at_period_end": false,
            "status": "active",
            "start_date": "2020-01-01 00:00:00",
            "canceled_at": null,
            "upzelo_id": "upz_sub_1234"
        },
        "flow": {
            "title": "High-value customers",
            "reason": "Matched audience"
        },
        "app_id": "upz_app_1234",
        "test_mode": true,
        "request_type": "cancel"
    }
}
```

{% endtab %}
{% endtabs %}