---
title: "How to create and configure webhooks"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_create_and_configure_webhooks-icon.png
date: 2024-09-04T00:00:00.000Z
tag: Guides
description: "This guide goes over how to create and configure webhooks with Unified.to. Webhooks allow you to receive real-time data events when there are updates in your..."
url: "https://docs.unified.to/guides/how_to_create_and_configure_webhooks"
---

# How to create and configure webhooks
------
_September 4, 2024_

This guide goes over how to create and configure webhooks with Unified.to. Webhooks allow you to receive real-time data events when there are updates in your customers' accounts.


Looking for help with troubleshooting webhook issues? See: [How to troubleshoot unhealthy webhooks](https://docs.unified.to/guides/how_to_troubleshoot_unhealthy_webhooks).


## Before you begin


This guide assumes you have a basic understanding of [webhooks](https://docs.unified.to/concepts/webhooks).


## Create a webhook 


Webhooks and connections are closely related; webhooks can only be created from existing connections and you can create multiple webhooks off a single connection. If you delete a connection, any webhooks that are associated with it will also be deleted. 


There are two ways to create a webhook:


### Method 1: Use the Unified API  


Send a POST request to `/unified/webhook`(see below for configuration options). For example:


```javascript
POST /unified/webhook?include_all=true

{
	hook_url: `${YOUR_WEBHOOK_URL}`,
	connection_id: `${CONNECTION_ID}`
	object_type: 'ats_candidate', // data to subscribe to
	event: 'updated', // type of event to listen for
}
```


**API reference:** [Create a webhook](https://docs.unified.to/unified/webhook/Create_webhook_subscription)


By including the optional parameter `include_all` in the query, the webhook will receive all historical data for the connection (see:[ Get all initial data for a connection](https://docs.unified.to/guides/how_to_create_and_configure_webhooks#get-all-initial-data-for-a-connection)).


This is the payload that your server receives when webhook data comes in:


| Name      | Type                                                       | Desc                                                                                                                                                                                                                          |
| --------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | _object array_                                             | An array of objects specific to the webhook's connection. (eg. CRM contacts)                                                                                                                                                  |
| `webhook` | [_Webhook_](https://docs.unified.to/unified/webhook/model) | The webhook object. You can use the id to manage or delete your webhook.                                                                                                                                                      |
| `nonce`   | _string_                                                   | Random string                                                                                                                                                                                                                 |
| `sig`     | _string_                                                   | A security signature generated using HMAC-SHA1. It combines your workspace secret with the payload data and nonce i.e `HMAC-SHA1(workspace.secret, data + nonce)` . Use this to verify the authenticity of incoming webhooks. |
| `type`    | _enum_                                                     | `INITIAL-PARTIAL, INITIAL-COMPLETE, VIRTUAL, NATIVE`                                                                                                                                                                          |


A note on the `type` enums:

- `INITIAL-PARTIAL`: included with each page of results for the initial sync
- `INITIAL-COMPLETE`: included with last page (e.g. last 5 elements for the limit 100) of initial sync or with an empty list (no more results)
- `VIRTUAL`: included with every page when reading new data from a virtual webhook
- `NATIVE`: included with every page when reading new data from a native webhook

### Method 2: Use the Unified.to app


If you prefer to create webhooks through the UI, you can do so at [app.unified.to](https://app.unified.to/).

1. Navigate to **Integrations** > [**Webhooks**](https://app.unified.to/webhooks).
2. Click **New Webhook**.
3. Click on the input and a list of your connections will appear. Select the connection from which you want to create a webhook.
4. Choose how to configure your webhook (see below).
5. Click **Save**.

Information about the other fields can be found under their respective tooltips in the UI.


### Webhook configuration options


Whether you use the API or our web UI, these are the configuration options you can specify when creating a webhook:

1. **Object:** The data you are interested in e.g. Deal, Company, Application, etc.
2. **Event:** The events you want to subscribe to. Note: The _updated_ event will also be sent when the data object is first _created_.
3. **Type:** For integrations that support both native and virtual webhooks, select the type of webhook you want. Virtual webhooks are our way of supporting webhooks for API providers that don't offer them. For more details, see: [Understanding virtual webhooks](https://docs.unified.to/guides/understanding_virtual_webhooks#understanding-native-and-virtual-webhooks).
4. **Filter (optional):** Specify any properties you want to filter incoming events by. See: [Use filters to refine webhook events](https://docs.unified.to/guides/how_to_create_and_configure_webhooks#use-filters-to-refine-webhook-events)
5. **Fields (optional):**  Comma-separated list of fields to include in the webhook payload. Leave blank to include all fields. The 'raw' field is NOT included by default. If you want to include all fields as well raw, just enter 'raw'. To read more about raw fields, see: [Raw and custom fields](https://docs.unified.to/reference/fields).
6. **Interval (virtual webhooks only):** Specify how often you want Unified.to to poll the API provider for new data.

## List your webhooks


To view your webhooks, make a GET request to `/unified/webhook` or visit [app.unified.to](https://app.unified.to/) and navigate to Integrations > [**Webhooks**](https://app.unified.to/webhooks).


 **API reference:** [Get all webhooks](https://docs.unified.to/unified/webhook/Returns_all_registered_webhooks)


## Get all initial data for a connection


When you create a webhook, you can choose to fetch all existing data immediately. 

1. If you are using the API, add the `include_all` query parameter when creating the webhook.
2. If you are using the UI, check off **Initially sync all data** in the configuration options.

Once the initial sync is complete, you will receive a final payload with `type: INITIAL-COMPLETE` and the requested webhook will continue to work as normal.


**API reference:** [Create a webhook subscription](https://docs.unified.to/unified/webhook/Create_webhook_subscription)


## A note on retrieving webhook data


Our system will POST initial data to your webhook in chunk sizes up to the limit supported by the integration. The limit can be found on the integration details page under **Feature support**.  


When performing the initial retrieval, depending on the amount of data being sent, the integration's API's rate-limiting rules, and your server's performance, it 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 include the `include_all` parameter in the request.


After the initial retrieval is completed, whenever updated data is available, your webhook will be called with a list of data objects, up to the max limit.  If there are more entries than the limit, then your webhook URL will be POSTed to multiple times. 


For details about the webhook payload that is sent to your server, [click here](https://docs.unified.to/concepts/webhooks#webhook-payload).


## Specify which fields to receive from a webhook


If you only want a subset of fields when receiving updated data, you can define them with the `fields` parameter in both the API and the UI. This is useful if you don't want the entire payload being sent to your servers. For more details, see: [Fields](https://docs.unified.to/reference/fields).


**API reference:** [Create a webhook subscription](https://docs.unified.to/unified/webhook/Create_webhook_subscription)


## Use filters to refine webhook events


_Note: This feature is only available for virtual webhooks. For more information about virtual webhooks, see:_ [_Understanding virtual webhooks_](https://docs.unified.to/guides/understanding_native_and_virtual_webhooks#understanding-native-and-virtual-webhooks)


Some virtual webhooks support filters, allowing you to filter the events you receive. For instance, if you're subscribed to Deal events from a CRM, you could filter by `company_id` to only receive events from that specific company.


Filter availability varies by integration type and data model. To check which filters are supported for a particular webhook, refer to the **List** section under the **Feature Support** tab of the respective integration. Parameters that end in `_id` or `type` can be used as filter options when creating a webhook, helping you tailor your subscriptions to your specific needs.


## Trigger webhooks manually


If you don't want to wait for an event to come in while testing webhooks on a Tester plan, you can trigger a webhook call right away. 

1. In the web app, navigate to [Webhooks](https://app.unified.to/webhooks).
2. Click the **Trigger** icon next to your webhook:

    ![Untitled.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_create_and_configure_webhooks-0.png)


This can also be accomplished with the API.


**API reference:** [Trigger a webhook](https://docs.unified.to/unified/webhook/Trigger_webhook)


Note**:** When you trigger a webhook, we will schedule the next dispatch event to go out right away - this is treated like a regular webhook event. Therefore, if your webhook is listening for update events and no new updates have occurred since the last run, then no new events will be sent to your server.


## Frequently asked questions


**Is there a page_max_limit for webhooks?**


An integration's `page_max_limit` typically comes directly from the API provider. You can see that limit under the **Feature Support** tab on the integration details page**.** You don't have to set limits for webhooks; they will use the integration's max limit.


**Does changing the interval for virtual webhooks affect the initial retrieval?**


Increasing frequency of virtual webhooks has no effect on the initial retrieval of historical data. Each page read is scheduled to be read one after another as soon as possible. 


**How do I distinguish between an updated event and a created event?**


When a new data object is created, it triggers both created and updated events. If you want to track both of these events but also tell them apart, we recommend subscribing to the updated event and then compare `created_at` and `updated_at` for incoming data. If they are the same, that means the data object was newly created.


**What happens if the webhook dispatch fails? Is there a retry mechanism in place?**


Our retry mechanism will retry 3 times immediately before using a Fibonacci backoff strategy. Read more about it [here](https://docs.unified.to/guides/how_to_troubleshoot_unhealthy_webhooks#a-note-on-our-webhook-retry-mechanism).


**Why do I receive duplicate webhook events and how should I handle them?**


Duplicate webhook events can occur for several reasons:

- Some integrations (like HubSpot) trigger separate events for each property change on an object
- Rapid changes to objects can trigger multiple events that may arrive out of order due to network conditions

To handle duplicates effectively:

1. Always use the object's latest state when updating your database
2. Implement atomic writes to avoid race conditions. Only update records if the incoming data is newer:

```javascript
-- Pseudo-code example
IF incoming_object.updated_at >= stored_object.updated_at THEN
    UPDATE record
ELSE
    -- Skip update as we already have newer data
END IF
```


## See also

- [How to troubleshoot unhealthy webhooks](https://docs.unified.to/guides/how_to_troubleshoot_unhealthy_webhooks)
- [Understanding virtual webhooks](https://docs.unified.to/guides/understanding_virtual_webhooks#understanding-native-and-virtual-webhooks)