GeezerVison

"@trigger.dev/core": patch

"@trigger.dev/sdk": patch

Add `webhooks.hookdeck()`, a source for deliveries relayed through a Hookdeck connection. It verifies the `x-hookdeck-signature` header with the project's signing secret, keeps verifying while the secret is being rolled (Hookdeck sends the previous secret's signature in `x-hookdeck-signature-2`), and deduplicates retries on `x-hookdeck-eventid`. The event is the original provider's payload, so pass its type: `webhooks.hookdeck<Stripe.Event>()`. If the Hookdeck project's header prefix was changed, pass it as `webhooks.hookdeck({ headerPrefix })` so retries keep deduplicating.

title: "Trigger tasks from Hookdeck webhooks"

sidebarTitle: "Hookdeck webhooks"

description: "This example demonstrates how to use Hookdeck to receive webhooks and trigger Trigger.dev tasks."

description: "Forward webhooks from a Hookdeck connection to a hosted Trigger.dev endpoint, verified with the Hookdeck project's signing secret, and run a task for each event."

This example shows how to use [Hookdeck](https://hookdeck.com) as your webhook infrastructure to trigger Trigger.dev tasks. Hookdeck receives webhooks from external services, and forwards them directly to the Trigger.dev API. This gives you the best of both worlds: Hookdeck's webhook management, logging, and replay capabilities, combined with Trigger.dev's reliable task execution.

Declare the endpoint with `webhooks.hookdeck()` and subscribe a task to it. Hookdeck forwards the original provider's body unchanged, so pass that provider's event type. This example relays Stripe events:

import type Stripe from "stripe";

import { webhook, webhooks } from "@trigger.dev/sdk";

export const stripeViaHookdeck = webhooks.endpoint.define({

id: "stripe-via-hookdeck",

source: webhooks.hookdeck<Stripe.Event>(),

});

export const paymentSucceeded = webhook({

id: "payment-succeeded",

endpoint: stripeViaHookdeck,

filter: "event.type == 'payment_intent.succeeded'",

onEvent: async ({ event }) => {

console.log("Payment succeeded", event.id);

},

});

- Use Hookdeck as your webhook endpoint for external services

- Hookdeck forwards webhooks directly to Trigger.dev tasks via the API

- All webhooks are logged and replayable in Hookdeck

<Steps>

<Step title="Create a connection">

In the [Hookdeck dashboard](https://dashboard.hookdeck.com), create a [connection](https://hookdeck.com/docs/connections) from your source (for example a Stripe source) to an HTTP destination whose URL is the endpoint's URL. Keep the destination's authentication on **Hookdeck Signature**, the default for new destinations: Hookdeck only signs forwarded requests with it set.

</Step>

<Step title="Store the signing secret">

Copy the signing secret from **Settings > Secrets** in Hookdeck and set it as the endpoint's signing secret in the Trigger.dev dashboard. It's one secret for the whole Hookdeck project.

</Step>

</Steps>

Send a webhook to your Hookdeck source URL, or trigger a real event in the upstream provider. In Hookdeck, the event shows a `200` response from the destination. In Trigger.dev, the endpoint shows a succeeded delivery and the `payment-succeeded` task has a completed run with the Stripe event as its payload.

- **URL**: `https://api.trigger.dev/api/v1/tasks/<task-id>/trigger` (replace `<task-id>` with your task ID)

- **Method**: POST

- **Authentication**: Bearer token (create a named **Trigger only** environment API key and use it as `TRIGGER_SECRET_KEY`)

addHandler("transform", (request, context) => {

request.body = { payload: { ...request.body } };

return request;

Hookdeck retries and manual replays of the same event carry the same `X-Hookdeck-Eventid`, and the endpoint uses it as the [deduplication](/webhooks/deliveries#deduplication) key, so a retried event runs your task once.

If you changed the header prefix in the Hookdeck project's settings, the event id arrives under the new prefix. Pass the prefix so deduplication keeps working:

import type Stripe from "stripe";

import { webhooks } from "@trigger.dev/sdk";

export const stripeViaHookdeck = webhooks.endpoint.define({

id: "stripe-via-hookdeck",

source: webhooks.hookdeck<Stripe.Event>({ headerPrefix: "x-acme" }),

});

Create a [connection](https://hookdeck.com/docs/connections) that links your source (where webhooks come from) to the destination and transformation you created above.

You can also point a Hookdeck destination at the [trigger task API](/management/tasks/trigger) without a hosted endpoint. Hookdeck authenticates with your API key instead of a signature, and a transformation wraps the body in the `payload` field the API expects.

1. Create a destination with the URL `https://api.trigger.dev/api/v1/tasks/<task-id>/trigger`, method `POST`, and **Bearer token** authentication using a **Trigger only** environment API key.

2. Add a [transformation](https://hookdeck.com/docs/transformations):

This task will be triggered when Hookdeck forwards a webhook to the Trigger.dev API.

```javascript

addHandler("transform", (request, context) => {

request.body = { payload: { ...request.body } };

return request;

});

```

3. Create a connection from your source to that destination and transformation.

import { task } from "@trigger.dev/sdk";

export const webhookHandler = task({

id: "webhook-handler",

run: async (payload: Record<string, unknown>) => {

// The payload contains the original webhook data from the external service

console.log("Received webhook:", payload);

// Add your custom logic here

},

});

To test everything is working:

1. Set up your destination, transformation, and connection in [Hookdeck](https://dashboard.hookdeck.com)

2. Send a test webhook to your Hookdeck source URL (use the Hookdeck Console or cURL)

3. Check the Hookdeck dashboard to verify the webhook was received and forwarded

4. Check the [Trigger.dev dashboard](https://cloud.trigger.dev) to see the successful run of your task

This path has no deduplication of Hookdeck retries; each forwarded request triggers a run.

For more information on setting up Hookdeck, refer to the [Hookdeck Documentation](https://hookdeck.com/docs).

For more on Hookdeck, see the [Hookdeck documentation](https://hookdeck.com/docs).

| Key | Sources |

| --- | --- |

| A header | GitHub (`X-GitHub-Delivery`), Svix and Autumn (`svix-id`), Standard Webhooks, Loops and Granola (`webhook-id`), Linear (`Linear-Delivery`), PagerDuty (`X-Webhook-Id`), Jira (`X-Atlassian-Webhook-Identifier`), Zendesk (`X-Zendesk-Webhook-Invocation-Id`), Attio (`Idempotency-Key`), Shopify (`X-Shopify-Webhook-Id`) |

| A header | GitHub (`X-GitHub-Delivery`), Svix and Autumn (`svix-id`), Standard Webhooks, Loops and Granola (`webhook-id`), Linear (`Linear-Delivery`), PagerDuty (`X-Webhook-Id`), Jira (`X-Atlassian-Webhook-Identifier`), Zendesk (`X-Zendesk-Webhook-Invocation-Id`), Attio (`Idempotency-Key`), Shopify (`X-Shopify-Webhook-Id`), Hookdeck (`X-Hookdeck-Eventid`, or `<prefix>-eventid` with a custom header prefix) |

| A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`), Square, Slack and Typeform (`event_id`), Firecrawl (`webhookId`) |

The other named sources (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below.

| HMAC-SHA256 with `X-Hub-Signature-256` | `whatsapp()` |

| Shared secret in `X-Gitlab-Token` | `gitlab()` |

| Shared secret as `Authorization: Bearer` | `supabase()` |

| Hookdeck relay (HMAC-SHA256 with `X-Hookdeck-Signature`) | `hookdeck()` |

| Provider-specific HMAC | `calendly()`, `calCom()`, `sentry()`, `pagerduty()`, `vercel()`, `linear()`, `notion()`, `typeform()`, `docusign()`, `jira()`, `intercom()`, `zendesk()`, `attio()`, `workos()`, `elevenlabs()`, `vapi()`, `retell()`, `shopify()`, `metronome()`, `mux()`, `tailscale()`, `langfuse()`, `infisical()`, `planetscale()`, `plain()`, `firecrawl()` |

Provider IDs containing a hyphen use a camel case function name: the `cal-com` provider is `webhooks.calCom()`.

Slack also ships as a chat channel in `@trigger.dev/slack`.

`hookdeck()` verifies requests that a [Hookdeck](https://hookdeck.com) connection forwards to the endpoint. Hookdeck forwards the original provider's body unchanged, so pass that provider's event type:

import type Stripe from "stripe";

import { webhook, webhooks } from "@trigger.dev/sdk";

export const stripeViaHookdeck = webhooks.endpoint.define({

id: "stripe-via-hookdeck",

source: webhooks.hookdeck<Stripe.Event>(),

});

export const paymentSucceeded = webhook({

id: "payment-succeeded",

endpoint: stripeViaHookdeck,

filter: "event.type == 'payment_intent.succeeded'",

onEvent: async ({ event }) => {

console.log(event.id);

},

});

Use the endpoint URL as the connection's HTTP destination, keep the destination's authentication on Hookdeck Signature (the default for new destinations), and store the Hookdeck project's signing secret from **Settings > Secrets** as the endpoint's signing secret.

- **Secret rotation:** when you roll the signing secret in Hookdeck with an expiry, Hookdeck also signs each request with the previous secret in `X-Hookdeck-Signature-2`, so deliveries keep verifying until you store the new secret.

- **Deduplication:** retries dedupe on `X-Hookdeck-Eventid`, which is the same on every attempt of a Hookdeck event.

- **Custom header prefix:** if you changed the header prefix in the Hookdeck project's settings, pass it with `webhooks.hookdeck({ headerPrefix: "x-acme" })`. The prefix renames the event id header; the signature headers keep the `X-Hookdeck-` name.

Some sources also define a response for the provider's endpoint-validation request. These requests don't create deliveries or task runs.

"producer": true

},

"notes": ""

},

{

"id": "hookdeck",

"label": "Hookdeck",

"category": "hosting-infra",

"tier": "first-class",

"preset": null,

"signatureScheme": "hmac-sha256",

"aiRelevance": "medium",

"popularity": "medium",

"sampleSource": "handauthored",

"docsUrl": "https://hookdeck.com/docs/authentication",

"status": "complete",

"owner": "hookdeck-provider",

"checklist": {

"registryEntry": true,

"samples": true,

"roundTrip": true,

"producer": true

},

"notes": "relay: body is the upstream provider's payload; x-hookdeck-signature-2 carries the previous secret while a rotation is in progress"

}

]

}

import { type SampleRecord } from "../sampleRecord.js";

export const samples: SampleRecord[] = [

{

provider: "hookdeck",

providerLabel: "Hookdeck",

eventType: "payment_intent.succeeded",

name: "Stripe payment relayed",

description: "A Stripe `payment_intent.succeeded` event forwarded by a Hookdeck connection.",

body: {

id: "evt_3QhRb2LkdIwHu7ix0Wq1X9aB",

object: "event",

type: "payment_intent.succeeded",

created: 1792569600,

livemode: false,

data: {

object: {

id: "pi_3QhRb2LkdIwHu7ix0kT2mN4p",

object: "payment_intent",

amount: 4900,

currency: "usd",

customer: "cus_R8xQ2mLkd91Hu7",

status: "succeeded",

},

},

},

extraHeaders: {

"x-hookdeck-source-name": "stripe-production",

"x-hookdeck-attempt-count": "1",

"x-hookdeck-attempt-trigger": "INITIAL",

},

docsUrl: "https://hookdeck.com/docs/destinations",

provenance: { kind: "handauthored", snapshotDate: "2026-10" },

},

{

provider: "hookdeck",

providerLabel: "Hookdeck",

eventType: "order.created",

name: "Order created relayed",

description:

"A custom app's `order.created` event forwarded by a Hookdeck connection, on a manual retry.",

body: {

type: "order.created",

id: "ord_7Kp2Qw9Lm3",

created_at: "2026-10-21T09:00:00.000Z",

data: {

total: 129.5,

currency: "EUR",

customer: { id: "cust_48Fh2", email: "[email protected]" },

items: [{ sku: "TEE-BLK-M", quantity: 2 }],

},

},

extraHeaders: {

"x-hookdeck-source-name": "shop-orders",

"x-hookdeck-attempt-count": "2",

"x-hookdeck-attempt-trigger": "MANUAL",

},

docsUrl: "https://hookdeck.com/docs/destinations",

provenance: { kind: "handauthored", snapshotDate: "2026-10" },

},

import { samples as s_firecrawl } from "./firecrawl.js";

import { samples as s_gitlab } from "./gitlab.js";

import { samples as s_granola } from "./granola.js";

import { samples as s_hookdeck } from "./hookdeck.js";

import { samples as s_infisical } from "./infisical.js";

import { samples as s_intercom } from "./intercom.js";

import { samples as s_jira } from "./jira.js";

...s_firecrawl,

...s_gitlab,

...s_granola,

...s_hookdeck,

...s_infisical,

...s_intercom,

...s_jira,

nowMs: NOW_MS,

toleranceSeconds: 300,

},

{

provider: "hookdeck",

source: "https://hookdeck.com/docs/authentication",

body: '{"id":"evt_hookdeck_fixture","type":"payment_intent.succeeded","note":"Zoë"}',

secret: "hookdeck_fixture_secret",

headers: {

"x-hookdeck-signature": "3gqjNEFqbs5p4dNxA9fIzpEkE+YKzHRHZpA1gc9Z6QM=",

"x-hookdeck-eventid": "evt_hookdeck_fixture_delivery",

},

nowMs: NOW_MS,

},

{

provider: "hookdeck",

label: "hookdeck (secret rolled with a delay: old secret in x-hookdeck-signature-2)",

source: "https://hookdeck.com/docs/authentication",

body: '{"id":"evt_hookdeck_fixture","type":"payment_intent.succeeded","note":"Zoë"}',

secret: "hookdeck_fixture_secret",

headers: {

"x-hookdeck-signature": "MRtBJRv3K6j8+CUcDsJuwYudgKi52qz9yfISiM3FKCw=",

"x-hookdeck-signature-2": "3gqjNEFqbs5p4dNxA9fIzpEkE+YKzHRHZpA1gc9Z6QM=",

"x-hookdeck-eventid": "evt_hookdeck_fixture_delivery",

},

nowMs: NOW_MS,

},

{

provider: "supabase",

source: "https://supabase.com/docs/guides/database/webhooks",

});

}

describe("hookdeck headerPrefix", () => {

const body = '{"id":"evt_hookdeck_fixture","type":"payment_intent.succeeded","note":"Zoë"}';

const run = (headerPrefix: string | undefined, headers: Record<string, string>) =>

verify(

{ kind: "config", config: webhookProviderConfigs.hookdeck.config({ headerPrefix }) },

{

rawBytes: new TextEncoder().encode(body),

secret: "hookdeck_fixture_secret",

nowMs: NOW_MS,

headers,

url: "https://example.com/webhooks/v1/ingest/hookdeck_fixture",

}

);

const prefixed = {

"x-hookdeck-signature": "MRtBJRv3K6j8+CUcDsJuwYudgKi52qz9yfISiM3FKCw=",

"x-hookdeck-signature-2": "3gqjNEFqbs5p4dNxA9fIzpEkE+YKzHRHZpA1gc9Z6QM=",

"x-acme-eventid": "evt_acme_delivery",

"x-acme-requestid": "req_acme",

};

it("keeps verifying the x-hookdeck signature headers and dedupes on <prefix>-eventid", () => {

expect(run("X-Acme-", prefixed)).toMatchObject({

ok: true,

idempotencyKey: "evt_acme_delivery",

});

});

it("without the option, still verifies but cannot read the renamed event id", () => {

const verdict = run(undefined, prefixed);

expect(verdict.ok).toBe(true);

expect(verdict.idempotencyKey).not.toBe("evt_acme_delivery");

});