Agent skill

Fivetran Webhooks Skill

Receive and verify Fivetran webhooks. Use when setting up Fivetran webhook handlers, debugging X-Fivetran-Signature-256 verification, or handling data pipeline events like sync_start, sync_end, connection_failure, or transformation_succeeded.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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:

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:

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/
examples/nextjs/
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.

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

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

Local Development

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

Reference Materials

references/overview.md - Fivetran webhook concepts and payload
references/setup.md - Creating a webhook with the REST API
references/verification.md - Signature verification details