# 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.upzelo.com/integrations/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.