Understanding native and virtual webhooks
March 8, 2023
A webhook is a mechanism that allows a server to send a real-time notification to another server when a specific event occurs. It is sometimes called a "web callback" or "push API". This can include events such as an update to a candidate in an ATS or new deal creation in a CRM.
Unlike REST APIs that are used to "poll" a server for data, a webhook is sent by the data server back to your application whenever new data is available.
Webhooks can make your synchronization strategy less complicated since your application will receive updated data directly.
The traditional method of retrieving new data from an API (without a webhook) is by calling the List
Modern APIs and applications leverage webhooks for synchronization because of its simplicity and timeliness. You, the application developer, do not have to create a retry mechanism to actively poll the server for new data and deal with rate-limiting and other network errors. The hard work is done by the third-party API provider to send you the update when their data changes.
Webhooks are much more efficient than polling by reducing any unnecessary API requests and eliminating the need for your app to retain a polling state. According to a survey conducted by Zapier, "82% responded that they preferred webhooks over polling."
You first subscribe to receiving the data that you want to monitor for changes, by registering a webhook with the URL of your server's API endpoint.
Your server then listens to that URL and once it gets a message, it parses it to figure out which data has changed.
Webhooks sound great, right? However, there's an important caveat we have to mention.
Not all software vendors support webhooks. So instead of having to support a mix of webhooks and polled API requests, Unified.to has standarized this for you through virtual webhooks, where our system mimics real webhooks for all vendor integrations. That means that you, the application developer, do not have to handle both polled and pushed data updates.
Our proprietary technology will monitor your customers' connections for update to data objects and then notify your webhook URL of those changes. The actual data will be sent to your webhook URL so that you then do not have to call another API request to retrieve it.
You subscribe to and manage virtual webhooks exactly the same way as you would with real webhooks. There is no difference with how to handle webhooks on the Unified.to platform, regardless if the integration support webhooks natively or not. The Unified.to platform will manage all of the polling, rate-limiting, and state management so you don't have to. Of course, because of our strict security policies, we are still not storing any of your customers' data on our servers or data bases.
Once a customer authorizes an integration for your application with the Unified.to authorization system, you will get a
connection_id that represents that new connection.
You can then call the
That API request will return a webhook object with an
id which you can then use to delete the webhook when it is no longer needed. If you delete the connection, any associated webhooks will also be deleted.
When you first integrate with a customer's third-party account, you'll want to use Unified.to unified API to retrieve the relevant information. The first step is to initially retrieve all of the existing data and then the next step is to retrieve the updated data when it is changed.
- Initial retrieval
When you create a webhook with the
include_allparameter, Unified.to will retrieve all of the existing requested data. Our system will send your webhook that data in chunks of 100 entries until complete. Depending on the amount of data, the integration's API's rate-limiting rules, and your webhook server's performance, this could take a very long time. If you do not want to get all of the existing data (for example, you already have it, or don't need it), then do not send in the
- Updated data retrieval Anytime that updated data is available, your webhook will get called with a list of up to 100 entries of that requested object. If there are more than 100, then your webhook will be called multiple times.
- Triggering a retrieval
If you don't want to wait the whole hour, while testing webhooks on a Tester plan, you can use a manual trigger to re-schedule webhook to run right away. Simply click the "Trigger" icon next to your webhook. This can also be accomplished in the API.
- If your webhook in unavailable or returns an error when Unified.to sends data to it, we will try up to 3 times, waiting 1 second in between. If the error persists, we will back-off and retry based off of a Fibonacci delay sequence, starting with 1 minute.
- If the integration's API is unavailable or returns an error (such as a Rate-Limiting warning), we will back-off and retry based off of a Fibonacci delay sequence, starting with 1 minute.
- The Connection Logs will show all webhook attempts and errors.
health statusindicator with possible values of
Unhealthyvisible on the webhook page.
audit trailthat is limited to the last 100 activities
Last-timethat the webhook was run/checked