---
title: "Register a signed outbound webhook for one or more Taskade events"
method: POST
path: "/webhooks"
tags: ["Webhook"]
---

# Register a signed outbound webhook for one or more Taskade events

`POST /webhooks`

## Request

- Base URL: `https://www.taskade.com/api/v2`
- URL: `https://www.taskade.com/api/v2/webhooks`
- Auth: OAuth 2 and HTTP bearer
  - Authorization code: `https://www.taskade.com/oauth2/authorize`
  - Token URL: `https://www.taskade.com/oauth2/token`

Each delivery is a POST with a JSON body and three signature headers:

- `X-Taskade-Signature`: `sha256=<hex>`, the HMAC-SHA256 of the raw body, keyed with your `secret`.
- `X-Taskade-Timestamp`: the send time, in unix seconds.
- `X-Taskade-Signature-V2`: `sha256=<hex>`, the HMAC-SHA256 of `<timestamp>.<raw body>`, keyed with your `secret`.

To verify V2:

1. Read the raw request body before you parse the JSON.
2. Compute the HMAC-SHA256 of the `X-Taskade-Timestamp` value, a period (`.`) and the raw body. Use your `secret` as the key.
3. Compare `sha256=<your hex>` with `X-Taskade-Signature-V2` in constant time.
4. Reject the request if the timestamp is more than 5 minutes away from your clock.

The timestamp is part of the signed data, so a captured delivery fails the check after 5 minutes. A copy that arrives inside those 5 minutes still passes, so make your handler idempotent, or record each delivery that you process and skip a repeat. `X-Taskade-Signature` does not change, and receivers that verify it keep working.

## Request body

- object
  - `targetUrl` string, uri, required
  - `events` string[], required
  - `spaceIds` string[]

## Response `200`

Default response

- object
  - `ok` true, required
  - `webhook` object, required
    - `id` string, uri, required: Endpoint id - the target URL (use URL-encoded as the :id path param).
    - `url` string, uri, required
    - `events` string[], required
    - `spaceIds` string[], required: Spaces this webhook is scoped to; empty = all spaces.
    - `createdAt` string, date-time, required
  - `secret` string, required: HMAC signing secret - shown once. Store it now.

---

[API](https://skmtc.dev/taskade/apis/taskade-public-api-v2.md) - [All operations](https://skmtc.dev/taskade/apis/taskade-public-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/taskade/apis/taskade-public-api-v2/revisions/45f0e74ec083?raw)