# Trigger.dev Webhooks

## 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:

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

```

Python:

```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:

```typescript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/trigger-dev-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/trigger-dev-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/trigger-dev-webhooks/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.

| Event | Description |
| --- | --- |
| `alert.run.failed` | A run failed after its retries were exhausted |
| `alert.deployment.success` | A deployment succeeded |
| `alert.deployment.failed` | A deployment failed |
| `alert.error` | An error group alert (`new_issue`, `regression`, or `unignored`) |

> **For the full payload reference**, see [Trigger.dev alert webhooks](https://trigger.dev/docs/troubleshooting-alerts#alert-webhooks)

## Important Headers

| Header | Description |
| --- | --- |
| `x-trigger-signature-hmacsha256` | Hex HMAC-SHA256 of the raw body |

## Environment Variables

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

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trigger-dev-webhooks/references/overview.md) - Trigger.dev alert webhook concepts and payloads
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trigger-dev-webhooks/references/setup.md) - Creating the webhook alert and getting the secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trigger-dev-webhooks/references/verification.md) - Signature verification details and gotchas