# Taskade Webhooks

> Only webhooks registered through the Taskade public API (Pro plan and above) are supported. Legacy webhooks are unsigned and fail verification.

## When to Use This Skill

* How do I receive Taskade webhooks?
* How do I verify the `X-Taskade-Signature` header?
* How do I handle `task.due`, `task.assigned`, `comment.created`, or `project.created` events?
* Why is my Taskade webhook signature verification failing?
* Where do I find the Taskade webhook signing secret?

## Verification (core)

Every delivery carries `X-Taskade-Signature: sha256=<hex>`: the lowercase hex HMAC-SHA256 of the **raw request body**, keyed with the webhook's signing secret (UTF-8 bytes, used as-is). Nothing else is signed (no timestamp or ID), so there is no replay window to check. Accept the value with or without the `sha256=` prefix.

Node:

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

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  const sig = signatureHeader.trim().replace(/^sha256=/i, '');
  if (!/^[0-9a-f]{64}$/i.test(sig)) return false; // validate before decoding
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), expected);
}

```

Python:

```python
import hashlib, hmac, re

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not secret:
        return False
    sig = re.sub(r"^sha256=", "", signature_header.strip(), flags=re.I)
    if not re.fullmatch(r"[0-9a-fA-F]{64}", sig):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(bytes.fromhex(sig), expected)

```

In Express use `express.raw({ type: '*/*' })` so the body stays a `Buffer` whatever the content type. Reject a missing, malformed or mismatched signature with `401`.

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

## Common Event Types

| Event | Description |
| --- | --- |
| `task.due` | A task reaches its due date |
| `task.assigned` | A task is assigned to someone |
| `comment.created` | A comment is added |
| `project.created` | A project is created |
| `project.assigned` | A project is assigned |
| `project.joined` | Someone joins a project |

These are the six event names the docs use when registering a webhook (`"events": ["task.due", ...]`). The docs show no delivery body or event header for registered webhooks, so where a delivery names its event is undocumented. The examples read it from the payload (`event` or `type`) and log anything else. Don't use the payloads under "Receiving Taskade Events": they belong to no-code automations, not these deliveries.

## Important Headers

| Header | Description |
| --- | --- |
| `X-Taskade-Signature` | `sha256=<hex>` HMAC-SHA256 of the raw body |

## Environment Variables

```bash
TASKADE_WEBHOOK_SECRET=your_signing_secret   # `secret` from the registration response, shown only once

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskade-webhooks/references/overview.md) - Taskade webhook concepts and events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskade-webhooks/references/setup.md) - Registration and signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskade-webhooks/references/verification.md) - Signature verification details