Webhooks offer a way to quickly find out about changes to your Subscriptions that happen 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 and up. They are not sent in real time, and that is important to know for your implementation.
As an example, when integrating with webhooks:
- DO use them for non-time sensitive events.
- DO NOT use them for realtime events.
Read below for more examples.
Because webhooks are asynchronous events, we do our best to always send them in a timely manner. With this said, however, we DO NOT recommend on relying on webhooks for events that are time sensitive.
A good example of this is your signup path. We DO NOT recommend that you block a user from moving forward with provisioning or signup on your side based on the arrival of a webhook.
All of our signup paths have synchronous methods of being notified of the event:
-
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 the information about the subscription using the id you have received. -
With Chargify.js, you can securely capture credit card details in a signup form hosted on your own site and then make a synchronous API call to create a subscription. This gives you complete control of the customer’s experience so that they never have to leave your site.
Listening for the signup_success webhook is an excellent backup to make sure that 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 check on what may have happened.
Webhooks Delivery
Advanced Billing sends webhooks out as soon as possible. However, typical delivery timeframes vary and can not be guaranteed. Please ensure your application and integration will be able to accommodate normal webhook delivery at least an hour after the event has taken place.
You must also be prepared for events to arrive out of order, which can happen if many events occur at nearly the same time, or if there is a failure and delivery is retried later. These types of delays, or the order of the webhook delivery, can cause inconsistencies with your view of the data if you do not take precautions.
For example, when processing subscription_state_changed webhooks, you may want to verify that the previous_state matches your view of the subscription before updating to the new value. If not, and you are not sure what the correct subscription state should be, then ignoring the webhook payload and instead making an API call to get the latest information about the subscription is suggested.
We understand that our users expect webhooks to be delivered instantly. In many cases they are, but we must inform you to be under the expectation that under normal operating conditions, a delay of 5 to 10 minutes of delivery of webhooks is completely within the guidelines set for our users.
Webhooks and Events
If you do not see a webhook containing the information you are looking for, also check the /events and /invoice_events API endpoints to see if there is a relevant event. Instead of receiving webhooks, you can _pull_ the event information into your system by making API Calls. If you find an event and you would like to receive the information pushed as a webhook, please contact support to request that it be added (no promises!).