Webhooks

What are webhooks?

A webhook (also called a web callback or HTTP push API) is a method to provide external applications with real-time information about data changes in a platform.

A webhook delivers data to the application at the moment that there is a change, resulting in data being pushed. Unlike REST APIs where the application polls the API at regular intervals in order to get the changed data. This makes webhooks much more efficient for both providers and consumers.

This guide will give more context and webhooks and get you up and running with the configuration in Unify. We bundled this in the following sections:

Do you want to learn more about Webhooks? Read our blog post.

Pull versus Push

Pull via polling and Push via webhooks are two different techniques that can be used to retrieve data from an API. Polling involves periodically sending requests to the API to check for new data, while webhooks involve registering a callback URL with the API and receiving notifications when new data is available.

Typically when you integrate with an API, you need to pull data from it. This means that you make a request to the API to get the data you need. This is called a pull integration. To act on changes, you need to monitor the API for changes and pull the data when it changes.

A webhook is a way to receive update events being pushed instead of polling continuously for updates.

You can use webhooks to subscribe to certain events when they occur. When an event occurs that matches your webhook subscription, a POST HTTP request will be sent to your webhook URL.

When to use webhooks and when to poll?

In general, polling is recommended when the data being retrieved is not time-sensitive and does not need to be received immediately. Polling is also useful when the frequency of data updates is not known in advance, as it allows you to control the rate at which you retrieve data from the API.

Webhooks, on the other hand, are recommended when the data being retrieved is time-sensitive and needs to be received as soon as possible. Webhooks are also useful when the frequency of data updates is known in advance, as they allow the API to send notifications to your callback URL as soon as new data is available.

Use Webhooks when: If you need updated data in real-time or updates are not very frequent, webhooks are the perfect solution. Webhooks are also more resource-efficient as you only get notified when an event has happened.

Use Polling when: You don't need updates in real-time and the updates are very frequent You need to get the latest data from the API, even if there are no updates example: Every 1 hour, refresh the number of users.

The use cases for webhooks are endless. We have listed some of the most common use cases in our blog post Apideck: What is a webhook?.

Virtual Webhooks

Some APIs don’t natively support webhooks. To prevent you from building data polling infrastructure, we’re introducing Virtualized Webhooks to let our partners receive Webhook events about changes by polling API endpoints as part of the Unify platform.

Our proprietary polling engine monitors for changes in records inside APIs and notifies you about changes via unified webhook events, enabling new use cases and powerful features like bi-directional sync.

The Unify platform will handle all the sync & polling complexity ( like pagination, automatic retries, rate limits, change tracking, ...) for our partner.

This all happens without storing data on our end. Keeping sustainability and computing resources in mind.

There are 2 ways to subscribe to Unify events:

Via the Apideck Admin
Via the Apideck Webhook subscription API

Via the Apideck admin

Goto Configuration > Webhooks section or https://platform.apideck.com/webhooks

Here you can manage existing webhook subscriptions.

To create a new Webhook subscription, click the “Add Webhook”

Enter the delivery URL of the webhook endpoint from your system, and select the Unify API to be able to select the desired events you want to receive webhook events for.

The delivery URL will be validated upon creation, and it is expected to respond with an HTTP 200 status code to the POST request initiated by Unify. You can find more information about how the webhook delivery URL validation works here.

The validation request or event will contain a header

x-apideck-event-type: apideck.subscription.created

and request body structured as follows:

{"message":"Validating delivery URL"}

After you pressed “Create”, you are subscribed to the Unify Webhook events.

Via the Apideck Webhook subscription API

By using the Webhook API, you can manage Webhook subscriptions

Visit: https://developers.apideck.com/apis/webhook/reference#tag/Webhooks to find all the details on what data is needed or use our API explorer

How to activate webhook events for integrations?

For Unify to forward any webhook events for your integrations, the integration needs to support webhook events and it is necessary to register a Unify endpoint to receive their webhook events.

For integrations that support subscription management via their API, Apideck will try to auto-register the subscription.

For integrations, that do not support auto-registration Webhooks, it is needed that you, or the customer, activating the integration, have to enter the Unify endpoint in the web portal of the integration.

For example Quickbooks:

At the bottom of the connector configuration, you can find the unique Unify endpoint that is needed to be copied and pasted into your webhooks settings in QuickBooks.

Once this is done, Unify can receive the Webhooks events from the integration (Quickbooks in this example) and converts them to Unify events and push them to the delivery endpoint that you configured when registering webhooks in Unify.