# Taskrabbit Webhooks

Taskrabbit's Partner API sends webhooks so partners can track projects
without polling. Webhooks are **delivered via Svix**: endpoints, event
subscriptions, delivery logs and replays live in the **Svix Partner Dashboard**
you get during partner onboarding. Every webhook is signed by Svix with a secret
unique to your endpoint. Taskrabbit's docs say unverified webhooks should be
discarded.

## When to Use This Skill

* How do I receive Taskrabbit webhooks?
* How do I verify Taskrabbit webhook signatures (`svix-signature`)?
* How do I handle `project.completed`, `project.canceled` or `project.rescheduled`?
* Why is my Taskrabbit webhook signature verification failing?
* Where do I get the Taskrabbit webhook signing secret?

## Verification (core)

Svix signs `${svix-id}.${svix-timestamp}.${raw body}` with HMAC-SHA256, keyed with
the base64-decoded bytes after the `whsec_` prefix, and sends it base64-encoded in
`svix-signature` as space-delimited `v1,<sig>` entries. Use the official `svix`
SDK (Node and Python); it also enforces a 5-minute timestamp window and checks
every signature in constant time.

```javascript
import { Webhook } from 'svix'; // svix 2.x is ESM-only

const wh = new Webhook(process.env.TASKRABBIT_WEBHOOK_SECRET); // "whsec_..."
wh.verify(rawBody, {            // raw Buffer/string, never re-serialized JSON
  'svix-id': req.headers['svix-id'],
  'svix-timestamp': req.headers['svix-timestamp'],
  'svix-signature': req.headers['svix-signature'],
}); // throws WebhookVerificationError -> respond 400
const event = JSON.parse(rawBody.toString('utf8')); // verify() returns undefined in 2.x
// Taskrabbit payloads are flat: switch on event.event, not event.type

```

```python
from svix.webhooks import Webhook, WebhookVerificationError

Webhook(os.environ["TASKRABBIT_WEBHOOK_SECRET"]).verify(body, {  # body: raw bytes
    "svix-id": msg_id, "svix-timestamp": timestamp, "svix-signature": signature,
})  # raises WebhookVerificationError -> 400
event = json.loads(body)  # event["event"] == "project.completed"

```

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/taskrabbit-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/taskrabbit-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/taskrabbit-webhooks/examples/fastapi/). Manual (no-SDK) verification is in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskrabbit-webhooks/references/verification.md).

## Common Event Types

| Event | Triggered When | Extra fields |
| --- | --- | --- |
| `project.completed` | The Tasker has completed the project's work | — |
| `project.canceled` | A project has been canceled | `cancellation_reason` (`order_canceled`, `delivery_delayed`, `changed_mind`, `canceled_by_cs`) |
| `project.rescheduled` | A task in the project moved to a new start time | `new_start_time`, `previous_start_time` |

Every payload is a flat JSON object with `event`, `project_uuid`, `timestamp`
(ISO 8601) and optional `agreement_external_reference` (your own reference ID).
There is **no `type`/`data` envelope**. Use the `svix-id` header as the
idempotency key; Svix retries non-2xx responses with exponential backoff.

> **For payload examples**, see [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskrabbit-webhooks/references/overview.md) and [Taskrabbit's webhook docs](https://developer.taskrabbit.com/docs/webhooks-1).

## Environment Variables

```bash
# Endpoint signing secret from the Svix Partner Dashboard (starts with whsec_)
TASKRABBIT_WEBHOOK_SECRET=whsec_xxxxx

```

## Local Development

For local webhook testing, run the Hookdeck CLI via `npx` (no install required):

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

```

No account required. Add the tunnel URL as an endpoint in the Svix Partner
Dashboard and send a test event from there.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskrabbit-webhooks/references/overview.md) - What Taskrabbit webhooks are, events and payloads
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskrabbit-webhooks/references/setup.md) - Configure endpoints in the Svix Partner Dashboard, get the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/taskrabbit-webhooks/references/verification.md) - SDK and manual signature verification, gotchas
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/taskrabbit-webhooks/examples/) - Runnable Express, Next.js and FastAPI examples with tests