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 Configure and Test Webhooks 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 (formerly Chargify.js) - Capture credit card details securely on your own site, then create a Subscription with a synchronous API call. See the Understand Maxio.js 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 Advanced Billing API calls. If you find an event you would like delivered as a webhook, contact support@maxio.com to request its addition, although availability is not guaranteed.

Related information

For delivery format, retry behavior, signature verification, and testing options, see the Configure and Test Webhooks help article.

To look up the event key and trigger for a specific webhook, see the Review Webhook Events help article.

For a full sample payload for every event, see the Review Webhook Payload Examples help article.

To review delivery history and resend a failed webhook, see the Monitor and Resend Webhooks help article.

For a vendor-neutral introduction to the concept itself, see What is a Webhook and How to Use One from GoCardless.