How to create and configure webhooks
September 30, 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.
Before you begin
- Be familiar with webhooks, which you can read more about in Introduction to 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:
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
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).
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 | 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 syncINITIAL-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 webhookNATIVE
: 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.
- Navigate to Integrations > Webhooks.
- Click New Webhook.
- Click on the input and a list of your connections will appear. Select the connection from which you want to create a webhook.
- Choose how to configure your webhook (see below).
- 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:
- Object: The data you are interested in e.g. Deal, Company, Application, etc.
- Event: The events you want to subscribe to. Note: The updated event will also be sent when the data object is first created.
- 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.
- Filter (optional): Specify any properties you want to filter incoming events by. See: Use filters to refine webhook events
- 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.
- 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 and navigate to Integrations > Webhooks.
API reference: Get all webhooks
Get all initial data for a connection
When you create a webhook, you can choose to fetch all existing data immediately.
- If you are using the API, add the
include_all
query parameter when creating the webhook. - 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
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.
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.
API reference: Create a 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
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.
- In the UI, navigate to Integrations > Webhooks
- Click the Trigger icon next to your webhook.
This can also be accomplished with the API.
API reference: Trigger a webhook
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.