Webhooks

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 webhooks

Learn how to create and manage webhooks for Fivetran events.

Creating a webhook is a two-step process:

1. Set up your application to receive webhook payloads at a secure, public URL.
2. 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.

URL

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.

Active

You can disable the delivery of webhook payloads by setting active to false.

Events

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)
• transformation_start
• transformation_succeeded
• transformation_failed
• connection_successful
• connection_failure
• create_connector
• pause_connector
• resume_connector
• edit_connector
• delete_connector
• force_update_connector
• resync_connector
• resync_table

Retries

Sometimes, a webhook that we sent for a particular event instance (for example, a transformation's start or a connection'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:

Connection request timeout

Webhooks have a 10-second connection request timeout. If your endpoint doesn't return an HTTP 200 OK status in 10 seconds, the webhook request fails, and Fivetran retries it based on the schedule outlined in Retries.

Automatic deactivation

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.

Signing

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.

Example of webhook payload

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"
  }
}

Fields

Related articles

Fivetran Logs

Release Notes

Webhooks API Reference