Trigger.dev Webhooks Skill

When to Use This Skill

• How do I receive Trigger.dev webhooks?
• How do I verify the Trigger.dev x-trigger-signature-hmacsha256 signature?
• How do I handle alert.run.failed or alert.deployment.failed events?
• Why is my Trigger.dev alert webhook signature verification failing?

Trigger.dev's outbound webhooks are alert notifications only (failed runs, deployments, error groups). They are not a general event stream for run lifecycle.

Verification (core)

Trigger.dev sends x-trigger-signature-hmacsha256: the bare hex HMAC-SHA256 of the raw body, keyed with the alert webhook secret as a UTF-8 string. There is no prefix, no timestamp and no base64 step. Compare timing-safe.

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');
  try {
    return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

Python:

import hmac, hashlib

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

Option: the Trigger.dev SDK

@trigger.dev/sdk exports webhooks.constructEvent(request, secret). It reads the header, verifies the signature, parses the body, and throws WebhookError on a missing or invalid signature:

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

const event = await webhooks.constructEvent(request, process.env.TRIGGER_DEV_WEBHOOK_SECRET!);

It takes a Web Request, so it suits Next.js and similar runtimes. The examples here verify manually so they work in Express and FastAPI without the SDK (the SDK is Node-only).

For complete handlers with route wiring, event dispatch, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

In Express, read the body with express.raw({ type: '*/*' }) so the raw bytes are available for any content type.

Common Event Types

The event type is the type field in the JSON body. There is no event-type header.

For the full payload reference, see Trigger.dev alert webhooks

Important Headers

Environment Variables

TRIGGER_DEV_WEBHOOK_SECRET=your_alert_webhook_secret   # Shown on the Alerts page when you create the webhook alert

Local Development

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

Reference Materials

• references/overview.md - Trigger.dev alert webhook concepts and payloads
• references/setup.md - Creating the webhook alert and getting the secret
• references/verification.md - Signature verification details and gotchas