Webhooks

Webhooks send a POST request to your server whenever tasks or comments change, so other systems can react.

1. Go to Settings → Integrations → Webhooks and click Add webhook.
2. Enter the Endpoint URL. It must use https://.
3. Pick the Events: task.created, task.updated, task.moved, task.completed, task.reopened, task.deleted, and comment.created.
4. Click Add webhook.
5. Copy the Signing secret. It isn't shown again.
6. Click Send test to send a ping event and check your endpoint.

What a delivery looks like

Each delivery is JSON with an id, the event type, created_at, workspace_id, the actor (id and name), and data.task with the task's id, key, title, description, board, list, assignees, labels, priority, dates, done state, and link.

The request carries these headers: Taskeni-Event, Taskeni-Delivery, and Taskeni-Signature.

Verify the signature

The signature header looks like t=<unix seconds>,v1=<hex>. Compute an HMAC-SHA256 of the timestamp, a dot, and the raw body with your secret, compare it with v1, and reject old timestamps.

import crypto from "node:crypto";

function isFromTaskeni(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const given = Buffer.from(parts.v1 || "");
  return fresh && given.length === expected.length && crypto.timingSafeEqual(given, Buffer.from(expected));
}

Retries and the delivery log

• Any response other than 2xx, a network error, or no answer within 10 seconds counts as a failure.
• Failed deliveries retry after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours, then stop. That's about 15 hours in all.
• Each webhook shows its Recent deliveries with status, HTTP code, and attempts. The log keeps 30 days.

Good to know

• Only owners and admins can manage webhooks.
• A workspace can have up to 10 webhooks.
• Use the Active switch to pause a webhook without deleting it.
• Webhooks are included on every plan.