# Guide to Taskade Webhooks: Features and Best Practices

[Taskade](https://www.taskade.com) is an AI-assisted workspace for projects, tasks, notes and team chat. Its registered webhooks notify your service when a task falls due or is assigned, a comment is added, or a project is created, assigned or joined. Teams use them to mirror Taskade work into other trackers, send reminders through their own channels, or kick off an AI review when a comment lands.

This guide covers registering signed webhooks through Taskade's public API, the six event names, verifying `X-Taskade-Signature`, and what to do about the parts Taskade hasn't documented yet, including the delivery body itself.

## What are Taskade webhooks?

Taskade has several webhook-like features, and only one of them is covered here. **Registered webhooks**, created with `POST /api/v2/webhooks` or under **Settings > API** on the Pro plan and above, are signed outbound deliveries to a URL you control. The URL doubles as the webhook's ID, and each registration lists its events and can be limited to particular workspaces.

Not covered: inbound automation webhooks (which send data into Taskade), the no-code "automation + HTTP action" route, and the older `subscribeWebhook` subscriptions. The legacy subscriptions still deliver but aren't signed, and the payloads shown under "Receiving Taskade Events" in Taskade's docs belong to the automation route rather than to registered webhooks.

## Taskade webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-taskade-signature` |
| Body | JSON |

## Events and payloads

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `task.due` | A task reaches its due date | Reminders, escalation |
| `task.assigned` | A task is assigned | Notify the assignee, sync to other tools |
| `comment.created` | A comment is added | Mirror discussion, trigger AI review |
| `project.created` | A project is created | Provision resources |
| `project.assigned` | A project is assigned | Ownership sync |
| `project.joined` | Someone joins a project | Onboarding |

These six names are what you pass in the `events` array when registering. Each event-workspace pair counts towards a limit of 100 per account, so a webhook for all six events in 20 workspaces would exceed it.

### Event Payload Structure

Taskade doesn't publish a delivery body for registered webhooks, and doesn't say which field or header carries the event name. The linked skill examples look for an `event` or `type` field and log anything else. Until you've inspected real deliveries, treat the body as opaque JSON: verify it, store it, and parse only the fields you've seen.

## Setting up Taskade webhooks

### Prerequisites

* A Taskade account on the Pro plan or above
* An API token for `POST /api/v2/webhooks`, or access to **Settings > API**
* An `https` endpoint URL of at most 2,048 characters (use the Hookdeck CLI for local development)

### Register Your Endpoint

1. Call `POST /api/v2/webhooks`, or open **Settings > API**.
2. Give the target URL, the `events` to receive, and `spaceIds` if you want to limit it to certain workspaces.
3. Read the `secret` in the response.

### Get Your Signing Secret

The registration response contains the signing `secret`, and Taskade shows it only that once. Save it as `WEBHOOK_SECRET` before doing anything else. If it's lost, delete the webhook and register it again to get a new one.

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

### Test a delivery

Start a local receiver and forward requests with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 taskade --path /webhooks/taskade

```

Register the CLI URL for `task.assigned` and `comment.created` in a test workspace, then assign a task and comment on it. Save both bodies: they're the only reliable reference for the payload shape.

## Securing Taskade webhooks

`X-Taskade-Signature` is `sha256=` plus the lowercase hex HMAC-SHA256 of the raw body, keyed with the registration secret. Compute it over the bytes as received, before any JSON parsing, and compare in constant time. Taskade's TypeScript sample compares the whole prefixed string after checking lengths; the verifier below strips the prefix and compares bytes, which is equivalent. Only the body is signed. See [verifying delivery signatures](https://docs.taskade.com/developers/webhooks#verify-delivery-signatures).

### Node.js verification

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

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-taskade-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature.startsWith('sha256=') ? signature.slice(7) : signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

As the event location is undocumented, the handler hashes the body for deduplication and reads the event name defensively. Anything it can't classify is stored for inspection rather than rejected.

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

function createTaskadeApp({ storeOnce, handlers }) {
  const app = express();
  app.post('/webhooks/taskade', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
    const bodyHash = crypto.createHash('sha256').update(req.body).digest('hex');
    let payload;
    try {
      payload = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
      return res.sendStatus(400);
    }
    const eventName = payload.event ?? payload.type ?? 'unknown';
    try {
      const isFirst = await storeOnce(bodyHash, eventName, payload);
      if (isFirst && handlers[eventName]) await handlers[eventName](payload);
      else if (isFirst) console.log('Stored unrecognised Taskade delivery', eventName);
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

```

Taskade doesn't say whether it retries a `503`, so don't count on it. Keep the stored copy so you can reprocess it yourself.

Hookdeck's Taskade source strips `sha256=` and compares the remainder with an HMAC of the body. Taskade receives `200` regardless of the outcome; requests that fail are recorded as failed verification and aren't forwarded. Legacy `subscribeWebhook` deliveries carry no signature and will always land there.

> **Make Taskade events dependable.** [Hookdeck Event Gateway](/event-gateway) verifies every registered Taskade webhook, keeps each delivery for inspection while the payload is undocumented, and retries your service when it's down.

## Taskade webhook limitations and pain points

### Undocumented delivery payload

**The Problem:** You can't write a typed parser or a router from the docs.

**Why It Happens:** Taskade documents event names for registration but no delivery body or event header for registered webhooks. The examples that do exist belong to the automation feature.

**Workarounds:**

* Collect real deliveries for each event before building handlers.
* Keep handlers tolerant of missing fields, and log unknown shapes.

**How Hookdeck Can Help:** Hookdeck stores every request body and header, which gives you a reference set of real payloads from the first day.

### No stated retries or timeout

**The Problem:** You don't know whether a failed delivery comes back.

**Why It Happens:** Taskade's docs give no timeout, success criterion or retry policy.

**Workarounds:**

* Respond quickly and queue processing.
* Re-read task and project state from the Taskade API after an outage.

**How Hookdeck Can Help:** Hookdeck accepts each delivery at once and retries your endpoint according to rules you set.

### One-time secret

**The Problem:** A lost secret makes the webhook unverifiable.

**Why It Happens:** The secret is returned only in the registration response.

**Workarounds:**

* Register webhooks from a script that writes the secret straight to your secrets manager.
* If it's lost, delete and re-register.

**How Hookdeck Can Help:** Keep the secret on the Hookdeck source, so your downstream services never need a copy.

### Legacy subscriptions are unsigned

**The Problem:** Older integrations keep receiving events that can't be verified.

**Why It Happens:** Deprecated `subscribeWebhook` subscriptions still deliver, without a signature.

**Workarounds:**

* Re-register each legacy subscription through `POST /api/v2/webhooks` and remove the old one.

**How Hookdeck Can Help:** Unsigned legacy deliveries show up as failed verifications on the Hookdeck source, which makes leftover subscriptions easy to find.

### Subscription limit

**The Problem:** Large organisations run out of event-workspace combinations.

**Why It Happens:** An account can have at most 100.

**Workarounds:**

* Subscribe only to events you act on, and avoid scoping when every workspace needs the same events.

**How Hookdeck Can Help:** One registration into Hookdeck can fan out to several destinations, so separate consumers don't each need their own Taskade webhook.

## Best practices

### Verify before parsing

Taskade signs the raw bytes, so read the body with `express.raw()` and verify first. Re-serialised JSON won't match.

### Record the URL you registered

The target URL is the webhook's ID. Keep it alongside the secret, because changing the URL means registering a new webhook.

### Use the API for state

Webhooks tell you something changed. When a handler needs full task or project details, fetch them from Taskade's API rather than relying on an undocumented payload.

### Retire legacy subscriptions

Audit for `subscribeWebhook` integrations and move them to registered webhooks so every delivery can be verified.

## Conclusion

Taskade's registered webhooks have the security basics in place: HTTPS-only targets, a per-webhook secret and an HMAC over the body. The rest is thin. There's no published delivery body, no event header and no retry policy, so a receiver has to store everything, parse cautiously and be ready to recover state from the API.

[Hookdeck Event Gateway](https://hookdeck.com) gives you stored payloads, retries and replay while Taskade's delivery behaviour remains undocumented.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Taskade webhooks reliably in minutes.