---
title: Understand Webhooks in Advanced Billing
url: https://docs.maxio.com/configuration/advanced-billing/webhooks/understand-webhooks-in-advanced-billing
applies_to: Advanced Billing
updated: 2026-10-26
---

# Understand Webhooks in Advanced Billing

Webhooks in Advanced Billing let you receive automated notifications about a wide range of events, including Subscription updates, Invoice creation, payment activity, and Customer record changes. You subscribe to specific events, and Advanced Billing sends data directly to a URL you specify whenever one of those events occurs. This makes webhooks an efficient way to stay informed and keep the records in your own system accurate and up to date.

## Prerequisites

Nothing is delivered until webhooks are switched on for your site and at least one endpoint exists to receive them. Enable webhooks, add an endpoint URL, and subscribe that endpoint to the events you want. See the <a href="https://docs.maxio.com/configuration/advanced-billing/webhooks/configure-and-test-webhooks" target="_blank" rel="noopener noreferrer">Configure and Test Webhooks</a> help article.

## Webhooks are asynchronous

Webhooks are *asynchronous*. Delivery times range from a few seconds to longer periods. They are not sent in real time, which is important to understand for your implementation.

> **Important:** Do not rely on webhooks for time-sensitive events. Blocking a user from provisioning or signup on your side until a webhook arrives leaves that user waiting on a delivery you cannot predict.

Use webhooks for events that are not time-sensitive, and use a synchronous method for anything a user is waiting on. Most signup paths offer a synchronous alternative, though the approach varies by path and some methods need specific configuration:

- **Public Signup Pages and Offer Signup Pages** - Configure the Return URL and its parameters to redirect the Customer back to your site after signup, including the `subscription_id` for an API retrieval call.
- **Maxio.js** - Capture credit card details securely on your own site, then create a Subscription with a synchronous API call. See the <a href="https://docs.maxio.com/configuration/advanced-billing/maxiojs/understand-maxiojs" target="_blank" rel="noopener noreferrer">Understand Maxio.js</a> help article.
- **Other custom integrations** - May need a direct API call after signup to confirm Subscription creation.

Listening for the `signup_success` webhook is a good backup to catch anything missed. By the time you receive it, you should already have a record of the Subscription. If not, you can process it or alert someone to investigate.

## Webhooks delivery

Maxio aims for instant delivery, but plan for potential delays. Under normal operating conditions, most webhooks are delivered within 5 to 10 minutes, which is within Maxio's standard guidelines. Occasional delays of up to an hour occur during high system load, event congestion, or retry scenarios. These delays are considered acceptable, so build your integration to handle them.

Be prepared for events to arrive out of order. This happens when many events occur at the same time, or when a failure causes delivery to be retried. Delays and order inconsistencies lead to data discrepancies if you do not take precautions.

*Example:* When processing `subscription_state_change` webhooks, verify that `previous_state` matches your view of the Subscription before updating to the new value. If it does not match, and you are unsure of the correct state, ignore the webhook payload and make an API call to retrieve the latest Subscription information instead.

## Webhooks and events

If you do not see a webhook carrying the information you need, check the `/events` and `/invoices/events` API endpoints for a relevant event. Instead of receiving webhooks, you can pull event information into your system with <a href="https://developers.maxio.com/http/getting-started/overview" target="_blank" rel="noopener noreferrer">Advanced Billing API</a> calls. If you find an event you would like delivered as a webhook, contact [support@maxio.com](mailto:support@maxio.com) to request its addition, although availability is not guaranteed.

For a vendor-neutral introduction to the concept itself, see <a href="https://gocardless.com/en-us/guides/posts/webhooks/" target="_blank" rel="noopener noreferrer">What is a Webhook and How to Use One</a> from GoCardless.
