Webhooks offer a way to quickly find out about changes to your subscriptions that occur within Advanced Billing. You can subscribe to events of interest, and we’ll post data to the URL you specify when one of those events occurs.
Related Topic: What is a webhook and how to use one (GoCardless article)
Webhooks are Asynchronous
Webhooks are asynchronous events. Delivery times can range from a few seconds to longer periods. They are not sent in real-time, which is important to understand for your implementation.
For example, when integrating with webhooks:
- DO use them for non-time-sensitive events.
- DO NOT use them for real-time events.
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.
All of our signup paths offer synchronous methods to notify you of events:
-
With Public Signup Pages or Offer Signup Pages, you can configure the Return URL and Parameters to redirect the customer back to your site after signup and include the
subscription_idin the URL. You can then make an API call to retrieve subscription information using this ID. -
With Chargify.js, you can securely capture credit card details in a signup form hosted on your own site and make a synchronous API call to create a subscription. This gives you complete control over the customer’s experience so that they never leave your site.
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
Advanced Billing sends webhooks as soon as possible. However, typical delivery timeframes vary and cannot be guaranteed. Ensure your application and integration can handle webhook delivery delays of up to an hour.
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.
While we strive for instant delivery, users should expect delays of 5 to 10 minutes under normal operating conditions, which is within our guidelines.
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 (no guarantees).