Webhooks

Listen for Upzelo events so your integration can automatically trigger reactions

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

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

Flow Started

{
    "data": {
        "type": "flow.started",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
    }
}

Flow Abandoned

{
    "data": {
        "type": "flow.abandoned",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
    }
}

Subscription

Pause

{
    "data": {
        "type": "subscription.pause",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
    }
}

Skip Charge

{
    "data": {
        "type": "subscription.skip-charge",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
        }
    }
}

Plan Change

{
    "data": {
        "type": "subscription.plan-change",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
    }
}

Free Period

{
    "data": {
        "type": "subscription.free-period",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
    }
}

Discount

{
    "data": {
        "type": "subscription.discount",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
    }
}

Cancel

{
    "data": {
        "type": "subscription.cancelled",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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,
    }
}

Requests

New Request

{
    "data": {
        "type": "request.created",
        "attempt": 1,
        "customer": {
            "external_id": "cus_1234",
            "name": "Richard Hendricks",
            "email": "[e-mail]",
            "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"
    }
}