# Pipedream Webhooks

## When to Use This Skill

* How do I receive Pipedream Connect trigger webhooks (events emitted by deployed triggers)?
* How do I verify the Pipedream `x-pd-signature` webhook signature?
* Why is my Pipedream webhook signature verification failing?
* How do I handle `CONNECTION_SUCCESS` / `CONNECTION_ERROR` when an end user connects an account?
* Where do I find the Pipedream webhook signing key?

## Two kinds of Pipedream Connect webhooks

| Webhook | Sent to | Signed? |
| --- | --- | --- |
| **Trigger webhooks** (events emitted by [deployed triggers](https://pipedream.com/docs/connect/components/triggers)) | Trigger-level `webhook_url`, or the project-level webhook URL for the environment | **Yes**: `x-pd-signature` |
| **Connection webhooks** (`CONNECTION_SUCCESS`, `CONNECTION_ERROR`) | The `webhook_uri` passed when creating a Connect token | **Not documented as signed** |

> **Caveat:** Pipedream only documents Connect **trigger** webhooks as signed. Connection webhooks and plain workflow HTTP requests carry no documented signature, so `x-pd-signature` verification does not apply to them. Protect a connection webhook URL with a secret of your own (e.g. a random `?token=` in `webhook_uri`) and confirm the account with the Retrieve Account API before trusting the payload.

## Verification (core)

Trigger webhook deliveries carry:

```
x-pd-signature: t=1616000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

```

`v1` is the HMAC-SHA256 hex digest of `<t>.<raw body>`, keyed with the signing key as a UTF-8 string. Compare in constant time and reject `t` more than 300 seconds old (Pipedream's replay guidance).

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

function verifyPipedreamSignature(rawBody, header, signingKey, toleranceSeconds = 300) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split(/=(.*)/s, 2)));
  const { t, v1 } = parts;
  if (!/^[0-9]+$/.test(t || '') || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false; // replay

  const expected = crypto.createHmac('sha256', signingKey)
    .update(`${t}.`).update(rawBody) // raw bytes, never re-serialised JSON
    .digest('hex');
  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1.toLowerCase()), Buffer.from(expected));
}

```

Python: `hmac.new(key.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()` compared with `hmac.compare_digest`.

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

Pipedream has no SDK helper for webhook verification (`@pipedream/sdk` only manages webhooks and signing keys), so every example verifies manually.

## Common Event Types

| Event | Webhook | Description |
| --- | --- | --- |
| `CONNECTION_SUCCESS` | Connection (unsigned) | End user connected an account. `account.id` (`apn_…`) and `account.external_id` are in the body; credentials are **not**, so fetch them with Retrieve Account |
| `CONNECTION_ERROR` | Connection (unsigned) | The connect flow failed; `error` holds the message |
| Trigger event | Trigger (signed) | Whatever the deployed trigger emitted (e.g. a GitLab issue from `gitlab-new-issue`). There is no Pipedream-level event type field, so route on which trigger/URL it came from |

See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pipedream-webhooks/references/overview.md) for payloads.

## Environment Variables

```bash
PIPEDREAM_WEBHOOK_SIGNING_KEY=your_pipedream_signing_key   # Trigger webhooks; shown once when the URL is saved
PIPEDREAM_CONNECT_WEBHOOK_TOKEN=random_string              # Optional; checked against ?token= on connection webhooks

```

## Local Development

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

```

Set the printed URL as the project webhook URL (or a trigger's `webhook_url`), copy the signing key, and deploy a trigger.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pipedream-webhooks/references/overview.md) - Trigger vs connection webhooks, payloads, events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pipedream-webhooks/references/setup.md) - Project-level and trigger-level webhook URLs, signing keys, Connect tokens
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pipedream-webhooks/references/verification.md) - Header format, algorithm, replay window, gotchas