As noted in a previous blog post, there are different ways to get information out of Recurly, and each option has different pros and cons depending on the specific objective. Using the right tool for the task at hand ensures an efficient use of resources and an improved experience for both you and your customers.

For example, webhooks are a very effective means to obtain information. A webhook is an HTTP callback that occurs when something happens. It’s a simple, automated event-notification system. A web application that has implemented webhooks will POST a message to a designated URL to trigger additional events or notifications.

When to use webhooks (and when not to)

One very common misuse of the API is when a merchant constantly polls the application with a GET request, as shown below:

GET process diagram

This is not an efficient way to integrate with Recurly! It’s a very resource-intensive protocol, and these constant queries for information cause several problems, not the least of which is the merchant will quickly hit their rate limit of API calls. Once they reach their limit, further GET requests will fail.

A much better method instead of a GET request is to wait for Recurly to POST the information the business needs, via a webhook, which is a push-based system rather than a GET system.

For example: a new user subscribes. The merchant uses the API for the initial provisioning only but relies on webhooks thereafter for any changes in status.

POST process diagram

The merchant, in this case, stores the customer data locally and assumes from that point on that everything is going well (for example, the subscription renews and the payment successfully goes through) unless or until they hear otherwise, via a webhook. There’s no need to constantly ping the API when you have webhooks set up that will alert you to customer events. And by storing customer information locally -- things like what plan they are on, what their next bill date is, etc. -- the data is readily available without having to use a data query.

It is, however, a good idea to use the API for the initial provisioning because webhooks events are not always in real time, and their order is not always maintained. But they are the best means to receive notifications about customer changes and then act on that information.

Here’s a breakdown of the main differences between webhooks and the API:

Webhooks API table

Webhooks are also great for obtaining and storing real-time data, whereas the API will only provide the current state of the subscription, but no historical data. Many merchants with data warehousing solutions store the webhooks data as it’s received and build up their database this way, giving them easier access to the data when they need it.

Webhooks for dunning

Webhooks are also perfect for dunning. When a customer’s payment fails, the merchant receives a webhook notification. They can then take an action, such as showing a “Past Due” or other banner on the user’s account until a successful payment is made. Indeed, showing an in-app alert on a customer’s account is one of the best ways to get customers to act in responses to a failed transaction.

Declined payment screen

Another less forgiving method is to show the banner on the customer’s login page and prevent them from logging in until they make a payment. If you go this route, you should also include a button or link on the login page that will take the customer to a payment screen where they can update their payment information.

As the dunning process proceeds, at each step in the cycle a webhook can notify the merchant of the result of the collection attempt, letting the business take the appropriate action, such as temporarily blocking the user’s account or removing the block when the payment is received.

If the dunning process fails completely, the merchant should expire the subscription and place a past-due balance on the account which will need to be paid if the customer wants to return. In that case, they will not be able to simply reactivate their subscription, but will have to resubscribe and re-enter their billing information, and this subscription will likely have a new billing cycle.

Of course, if this is occurring frequently, it may be that your dunning process is either too short and not giving customers enough time to update their payment information. Or it could be that the dunning emails or other notifications are ineffective.

For more ideas on how to use webhooks, read our blog post on “Making the Most of Recurly With Multiple Webhooks.”