Agent skill

Taskrabbit Webhooks Skill

Receive and verify Taskrabbit webhooks from the Taskrabbit Partner API (Delivery and Home Services). Use when setting up a Taskrabbit webhook handler, verifying the Svix signature headers (svix-id, svix-timestamp, svix-signature) with a whsec_ secret from the Svix Partner Dashboard, debugging Taskrabbit signature verification, or handling project.completed, project.canceled and project.rescheduled events.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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.

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

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/, examples/nextjs/, examples/fastapi/. Manual (no-SDK) verification is in 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 and Taskrabbit's webhook docs.

Environment Variables

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

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 - What Taskrabbit webhooks are, events and payloads
references/setup.md - Configure endpoints in the Svix Partner Dashboard, get the signing secret
references/verification.md - SDK and manual signature verification, gotchas
examples/ - Runnable Express, Next.js and FastAPI examples with tests