# Fivetran Webhooks

## When to Use This Skill

* How do I receive Fivetran webhooks?
* How do I verify the `X-Fivetran-Signature-256` header?
* How do I handle `sync_end`, `sync_start`, or `connection_failure` events?
* Why is my Fivetran webhook signature verification failing, or why was my webhook not created?
* How do I trigger downstream jobs (dbt, alerts, reloads) when a Fivetran sync finishes?

## Verification (core)

Fivetran signs the **raw request body** with HMAC-SHA256 keyed on the `secret` you passed to the Webhooks REST API, and sends the digest as hex in `X-Fivetran-Signature-256`. There is no timestamp and no prefix. Fivetran's own example compares **uppercase** hex, so compare case-insensitively (normalise both sides). The header is sent **only if you set a `secret`** when creating the webhook.

Node:

```javascript
const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex').toUpperCase();
  const actual = signatureHeader.trim().toUpperCase();
  try {
    return crypto.timingSafeEqual(Buffer.from(actual), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

```

Python:

```python
import hmac, hashlib

def verify(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
    if not signature_header or not secret:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest().upper()
    return hmac.compare_digest(signature_header.strip().upper(), expected)

```

> **For complete handlers with route wiring, event dispatch, and tests**, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/fivetran-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/fivetran-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/fivetran-webhooks/examples/fastapi/)

## Common Event Types

The event name is in the JSON body (`event`); there is no event-type header.

| Event | Description |
| --- | --- |
| `sync_start` | A connection sync started |
| `sync_end` | A connection sync ended (`data.status` is `SUCCESSFUL` or `FAILED`) |
| `status` | Connection status change (deprecated by Fivetran) |
| `transformation_start` | A transformation run started |
| `transformation_succeeded` | A transformation run succeeded |
| `transformation_failed` | A transformation run failed |
| `connection_successful` | Connection setup test passed |
| `connection_failure` | Connection setup test failed |
| `create_connector` / `pause_connector` / `resume_connector` / `edit_connector` / `delete_connector` / `force_update_connector` / `resync_connector` / `resync_table` | Connection lifecycle changes |

> **For the full event list**, see [Fivetran Webhooks](https://fivetran.com/docs/rest-api/webhooks).

## Important Details

| Item | Value |
| --- | --- |
| Signature header | `X-Fivetran-Signature-256` (only if a secret was set) |
| Algorithm | HMAC-SHA256 of the raw body, hex digest |
| Setup | REST API only (`POST /v1/webhooks/account` or `/v1/webhooks/group/{groupId}`) |
| Test request | One POST on create/activate; non-2xx or unreachable means the webhook is **not created** (HTTP 400) |
| Timeout | 10 seconds to return `200 OK` |
| Retries | Up to 5 over 24 hours (6 min, 21 min, ...), then dropped; deactivated after 3+ days of failures |

## Environment Variables

```bash
FIVETRAN_WEBHOOK_SECRET=your_webhook_secret   # The "secret" value sent when creating the webhook

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 fivetran --path /webhooks/fivetran

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/fivetran-webhooks/references/overview.md) - Fivetran webhook concepts and payload
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/fivetran-webhooks/references/setup.md) - Creating a webhook with the REST API
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/fivetran-webhooks/references/verification.md) - Signature verification details