Webhooks Overview

Webhooks in Advanced Billing allow you to receive automated notifications about a wide range of events, including Subscription updates, Invoice creation, payment activity, and Customer record changes. You can subscribe to specific events and have data sent directly to a URL you specify whenever those events occur. This makes Webhooks an efficient way to stay informed and maintain accurate, up-to-date records in your system.

Related topic: What is a Webhook and How to Use One (GoCardless article)

Webhooks are Asynchronous

Because Webhooks are asynchronous, we strive to send them in a timely manner. However, we do not recommend relying on Webhooks for time-sensitive events.

For example, we do not recommend blocking a user from provisioning or signup on your side based on the arrival of a Webhook.

Most signup paths offer synchronous methods to notify you of events, though the approach varies by path and some methods may require specific configuration. For example:

• Public Signup Pages / Offer Signup Pages: Configure the Return URL and 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 via a synchronous API call.
• Other custom integrations: May require a direct API call after signup to confirm Subscription creation.

Listening for the signup_success Webhook is an excellent backup to ensure nothing has been 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

While we strive for instant delivery, users should plan for potential delays. Under normal operating conditions, most Webhooks are delivered within 5 to 10 minutes, which is within our standard guidelines. Occasional delays of up to an hour may occur during high system load, event congestion, or retry scenarios, and these are considered acceptable, but your integration should be built to handle them.

Be prepared for events to arrive out of order, which can occur if many events happen simultaneously or if there is a failure and delivery is retried. These delays or order inconsistencies can lead to data discrepancies if precautions are not taken.

For example, when processing subscription_state_changed Webhooks, verify that the previous_state matches your Subscription view before updating to the new value. If not, and you are unsure of the correct state, ignore the Webhook payload and instead make an API call to retrieve the latest Subscription information.

Webhooks and Events

If you do not see a Webhook containing the information you need, check the /events and /invoice_events API endpoints for relevant Events. Instead of receiving Webhooks, you can pull Event information into your system via API calls. If you find an Event and would like it delivered as a Webhook, contact support@maxio.com to request its addition, although availability is not guaranteed.