Webhook Managementlink
Updated October 14, 2023
Our Webhook API is a RESTful API accessed by using either an HTTP client, such as wget or curl, or an HTTP library, which is a part of most modern programming language packages.
Our webhooks test project is a simple example that demonstrates how to ingest webhooks from Fivetran.
Create webhookslink
Learn how to create and manage webhooks for Fivetran events.
TIP: For examples of how to set up and use webhooks, see the code sample for your environment:
Creating a webhook is a two-step process:
- Set up your application to receive webhook payloads at a secure, public URL.
- Create a webhook with Fivetran to fire in response to particular events.
The Fivetran Webhook REST API lets you manage webhooks. You can also use the REST API to change the configuration of your webhook. For example, you can modify the payload URL and the list of events.
URLlink
The payload URL must be a secure site (HTTPS). If an insecure (HTTP) payload URL is received, Fivetran returns an HTTP 400 Bad Request
error. During the webhook creation or activation, we perform a single POST
request to the specified URL with a testing payload. If endpoint is not reachable or returns an unsuccessful status code, Fivetran does not create the webhook and returns an HTTP 400 Bad Request
error. You can skip this check by setting active
to false
during the webhook creation, but we still perform this test during the webhook activation.
Activelink
You can disable the delivery of webhook payloads by setting active
to false
.
Eventslink
When configuring a webhook, you can use the API to choose which events send you payloads. Subscribing to only specific events you want to listen for minimizes the number of HTTPS requests to your server.
We support the following events:
- sync_start
- sync_end
- status (deprecated)
- dbt_run_start
- dbt_run_succeeded
- dbt_run_failed
- transformation_run_start (deprecated)
- transformation_run_succeeded (deprecated)
- transformation_run_failed (deprecated)
- connection_successful
- connection_failure
- create_connector
- pause_connector
- resume_connector
- edit_connector
- delete_connector
- force_update_connector
- resync_connector
- resync_table
NOTE: Fill out our survey if you want more event types supported by our Webhook Management API.
Retrieslink
Sometimes, a webhook that we sent for a particular event instance (for example, a transformation's start or a connector's sync end) may fail for various reasons, such as the relevant endpoint being unavailable, etc. In that case, we retry the webhook for up to 24 hours in increasing time intervals. We stop sending the webhook for the given event instance after retrying for 24 hours.
We use an exponential algorithm to calculate the intervals between the retries. We wait 6 minutes before the first retry, 21 minutes before the second retry, and so on. This approach allows us to make up to five webhook retries within the 24-hour period.
See how Fivetran calculates the times of retries following a failed initial attempt in the following example:
Initial attempt and following retries | Time |
---|---|
Initial attempt | 10:00 |
1st retry | 10:06 |
2nd retry | 10:27 |
3rd retry | 11:45 |
4th retry | 16:25 |
5th retry | 9:13 the next day |
NOTE: For each webhook event type within a given context (a given connector/transformation in a given group in your account), we send webhooks for each event instance independently of the other instances of that event. For example, you created a sync start webhook for a connector with the sync frequency of 6 hours. At the sync start at 00:12, Fivetran sent a sync start webhook that failed. Regardless of the number of retries and the final status of this webhook, Fivetran still will send another sync start webhook at the next sync start at 6:12.
Automatic deactivationlink
If a webhook consistently fails for more than three days and only responds with non-2xx codes, we deactivate it.
To activate the webhook again, ensure that the setup is correct by retrieving the webhook details and updating them with corrected information along with passing "active": true
in the request. Alternatively, you can create a new webhook.
Signinglink
The webhook payload can be signed if you specified a secret during the webhook creation. The signature is calculated based on the payload body using the SHA-256 HMAC algorithm.
Manage webhookslink
Our Webhook REST API supports the following webhook management actions:
- Create account webhook
- Create group webhook
- Retrieve webhook details
- Update webhook
- Delete webhook
- Retrieve the list of webhooks
- Test webhook
Create account webhooklink
This endpoint allows you to create a new webhook for the current account.
Requestlink
POST https://api.fivetran.com/v1/webhooks/account
{
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "my_secret"
}
content_copy
Request parameterslink
Name | Description |
---|---|
url (required) | Your webhooks URL endpoint for your application |
events (required) | The array of event types |
active | Boolean, if set to true , webhooks are immediately sent in response to events. Optional. true by default. |
secret | The secret string used for payload signing. Optional. |
Responselink
HTTP 200 OK
{
"code": "Success",
"message": "Account webhook has been created",
"data": {
"id": "program_quoth",
"type": "account",
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "******",
"created_at": "2022-04-29T09:41:08.583Z",
"created_by": "_airworthy"
}
}
content_copy
Fieldslink
Name | Description | Possible values |
---|---|---|
code | Response status code | |
message | Response status text | |
data | Response data | |
id | The webhook ID | |
type | The webhook type | account |
url | Your webhooks URL endpoint for your application | |
events | The array of event types | |
active | Boolean, if set to true , webhooks are immediately sent in response to events | |
secret | The secret string used for payload signing and masked in the response. | |
created_at | The webhook creation timestamp | |
created_by | The ID of the user who created the webhook |
Create group webhooklink
This endpoint allows you to create a new webhook for a given group.
Requestlink
POST https://api.fivetran.com/v1/webhooks/group/{group_id}
{
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "my_secret"
}
content_copy
Path parameterslink
Name | Description |
---|---|
group_id (required) | The group ID |
Request parameterslink
Name | Description |
---|---|
url (required) | Your webhooks URL endpoint for your application |
events (required) | The array of event types |
active | Boolean, if set to true , webhooks are immediately sent in response to events. Optional. true by default. |
secret | The secret string used for payload signing. Optional. |
Responselink
HTTP 200 OK
{
"code": "Success",
"message": "Group webhook has been created",
"data": {
"id": "recur_readable",
"type": "group",
"group_id": "_moonbeam",
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "******",
"created_at": "2022-04-29T10:45:00.000Z",
"created_by": "_airworthy"
}
}
content_copy
Fieldslink
Name | Description | Possible values |
---|---|---|
code | Response status code | |
message | Response status text | |
data | Response data | |
id | The webhook ID | |
type | The webhook type | group |
group_id | The group ID | |
url | Your webhooks URL endpoint for your application | |
events | The array of event types | |
active | Boolean, if set to true , webhooks are immediately sent in response to events | |
secret | The secret string used for payload signing and masked in the response. | |
created_at | The webhook creation timestamp | |
created_by | The ID of the user who created the webhook. |
Retrieve webhook detailslink
This endpoint allows you to retrieve details of the existing webhook for a given identifier.
Requestlink
GET https://api.fivetran.com/v1/webhooks/{webhook_id}
Path parameterslink
Name | Description |
---|---|
webhook_id (required) | The webhook identifier |
Responselink
HTTP 200 OK
{
"code": "Success",
"data": {
"id": "recur_readable",
"type": "group",
"group_id": "_moonbeam",
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "******",
"created_at": "2022-04-29T10:45:00.000Z",
"created_by": "_airworthy"
}
}
content_copy
Fieldslink
Name | Description | Possible values |
---|---|---|
code | Response status code | |
data | Response data | |
id | The webhook ID | |
type | The webhook type | account , group |
group_id | The group ID | |
url | Your webhooks URL endpoint for your application | |
events | The array of event types | |
active | Boolean, if set to true , webhooks are immediately sent in response to events | |
secret | The secret string used for payload signing and masked in the response. | |
created_at | The webhook creation timestamp | |
created_by | The ID of the user who created the webhook. |
Update webhooklink
The endpoint allows you to update the existing webhook with a given identifier.
Requestlink
PATCH https://api.fivetran.com/v1/webhooks/{webhook_id}
{
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_end",
"sync_start"
],
"active": true,
"secret": "my_secret"
}
content_copy
Path parameterslink
Name | Description |
---|---|
webhook_id (required) | The webhook identifier |
Request parameterslink
Name | Description |
---|---|
url | Your webhooks URL endpoint for your application |
events | The array of event types |
active | Boolean, if set to true , webhooks are immediately sent in response to events |
secret | The secret string used for payload signing and masked in the response. Optional. |
Responselink
HTTP 200 OK
{
"code": "Success",
"message": "Webhook has been updated",
"data": {
"id": "program_quoth",
"type": "account",
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "******",
"created_at": "2022-04-29T09:41:08.583Z",
"created_by": "_airworthy"
}
}
content_copy
Fieldslink
Name | Description | Possible values |
---|---|---|
code | Response status code | |
message | Response status text | |
data | Response data | |
id | The webhook ID | |
type | The webhook type | account , group |
group_id | The group ID | |
url | Your webhooks URL endpoint for your application | |
events | The array of event types | |
active | Boolean, if set to true , webhooks are immediately sent in response to events | |
secret | The secret string used for payload signing and masked in the response. | |
created_at | The webhook creation timestamp | |
created_by | The ID of the user who created the webhook. |
Delete webhooklink
This endpoint allows you to delete an existing webhook with a given identifier.
Requestlink
DELETE https://api.fivetran.com/v1/webhooks/{webhook_id}
Path parameterslink
Name | Description |
---|---|
webhook_id (required) | The webhook identifier |
Responselink
HTTP 200 OK
{
"code": "Success",
"message": "Webhook with id 'webhook_id' has been deleted"
}
content_copy
Retrieve the list of webhookslink
The endpoint allows you to retrieve the list of existing webhooks available for the current account.
Requestlink
GET https://api.fivetran.com/v1/webhooks
Request parameterslink
Name | Description |
---|---|
cursor | The paging cursor. Read more about pagination in our documentation |
limit | The number of records to fetch, accepts a number in the range of 1..1000, the default value is 100 |
Responselink
HTTP 200 OK
{
"code": "Success",
"data": {
"items": [
{
"id": "program_quoth",
"type": "account",
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "******",
"created_at": "2022-04-29T09:41:08.583Z",
"created_by": "_airworthy"
},
{
"id": "recur_readable",
"type": "group",
"group_id": "_moonbeam",
"url": "https://your-host.your-domain/webhook",
"events": [
"sync_start",
"sync_end"
],
"active": true,
"secret": "******",
"created_at": "2022-04-29T10:45:00.000Z",
"created_by": "_airworthy"
}
]
}
}
content_copy
Fieldslink
Name | Description | Possible values |
---|---|---|
code | Response status code | |
data | Response data | |
items | The collection of webhooks available for the current account | |
id | The webhook ID | |
type | The webhook type | account , group |
group_id | The group ID | |
url | Your webhooks URL endpoint for your application | |
events | The array of event types | |
active | Boolean, if set to true , webhooks are immediately sent in response to events | |
secret | The secret string used for payload signing and masked in the response. | |
created_at | The webhook creation timestamp | |
created_by | The ID of the user who created the webhook. |
Test webhooklink
The endpoint allows you to test an existing webhook. It sends a webhook with a given identifier for a dummy connector with identifier _connector_1
.
Requestlink
POST https://api.fivetran.com/v1/webhooks/{webhook_id}/test
{
"event": "sync_start"
}
content_copy
Path parameterslink
Name | Description |
---|---|
webhook_id (required) | The webhook identifier |
Request parameterslink
Name | Description |
---|---|
event (required) | Type of event that should be sent |
Responselink
HTTP 200 OK
{
"code": "Success",
"data": {
"succeed": true,
"status": 200,
"message": "SUCCESS"
}
}
content_copy
Example of webhook payloadlink
Fivetran sends webhooks with the following payload structure:
{
"event" : "sync_end",
"created" : "2021-08-18T11:38:34.386Z",
"connector_type" : "asana",
"connector_id" : "mystified_presiding",
"connector_name" : "mystified_presiding",
"sync_id" : "mystified_presiding",
"destination_group_id" : "deck_enjoy",
"data" : {
"status" : "SUCCESSFUL"
}
}
content_copy
Fieldslink
Name | Description | Possible Values |
---|---|---|
event | The event type | |
created | The event generation date | |
connector_type | The type of the connector for which the webhooks is sent | |
connector_id | The ID of the connector for which the webhooks is sent | |
connector_name | The name of the connector for which the webhooks is sent | |
sync_id | The sync for which the webhooks is sent | |
destination_group_id | The destination group ID of the connector for which the webhooks is sent | |
data | The response payload object. The object fields vary depending on the event type. | |
status | The webhook creation status | SUCCESSFUL , FAILED |