Source
Open app

Developers

Get told when something happens on a board, and read or write tickets from your own tools. Both are set up by an organization admin under Settings.

Webhooks

Each webhook is a POST of the JSON below to an HTTPS URL you choose. A response outside the 2xx range is retried five more times over about ten and a half hours, and each attempt appears in the delivery log for seven days. After twenty events in a row are given up on, the webhook is switched off until someone switches it back on.

{
  "id": "evt_7f3a…",
  "type": "ticket.completed",
  "occurredAt": "2026-11-08T09:30:00.000Z",
  "organizationId": "…",
  "data": {
    "projectId": "…",
    "subject": {
      "kind": "ticket",
      "id": "…",
      "ref": "NS-14",
      "label": "NS-14 — Fix the header"
    }
  }
}

Delivery is at-least-once, so use webhook-id, which stays the same across retries, to ignore an event you have already handled. Order is not guaranteed. Events cover every project in the organization, including private ones. ticket.assigned also carries data.assignee, and a sprint closed by hand sends sprint.completed and no sprint.ended.

  • ticket.created — Ticket opened
  • ticket.assigned — Ticket assigned
  • ticket.commented — Comment added
  • ticket.blocked — Ticket blocked
  • ticket.approved — Filed ticket approved
  • ticket.completed — Ticket closed
  • sprint.started — Sprint started
  • sprint.ended — Sprint ended
  • sprint.completed — Sprint completed
  • project.created — Project created
  • project.assigned — Team put on a project
  • member.joined — Someone joined
  • member.left — Someone left

Verifying a signature

Deliveries are signed to the Standard Webhooks specification, so an existing library will verify them. Verify against the raw request body, and reject old timestamps.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const key = Buffer.from(secret.replace("whsec_", ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return false;

  return headers["webhook-signature"].split(" ").some((entry) => {
    const actual = Buffer.from(entry.replace("v1,", ""), "base64");
    return actual.length === expected.length && timingSafeEqual(actual, expected);
  });
}

Slack and Discord

Paste an incoming webhook URL and pick the events to post. These use the same retries and delivery log as any other webhook; they just send a chat message in place of the JSON, and are not signed because those services have nowhere to check a signature.

API

Requests go to https://flexible-bird-801.eu-west-1.convex.site. Send a token from Settings as Authorization: Bearer nvp_…. A token acts with the permissions of the person who created it, narrowed to its scopes, and stops working if they leave the organization. Each token can make 600 requests every five minutes.

GET/api/v1/projectsprojects:read
GET/api/v1/projects/{key}/ticketstickets:read
POST/api/v1/projects/{key}/ticketstickets:write
GET/api/v1/tickets/{ref}tickets:read
POST/api/v1/tickets/{ref}/commentstickets:write
POST/api/v1/tickets/{ref}/movetickets:write
  • projects:read — List the projects this token can see.
  • tickets:read — List tickets and read one by its ref.
  • tickets:write — File tickets, comment on them and move them between columns.

The full schema is published as OpenAPI 3.1 at /api/v1/openapi.json.

Roadmap

  • Outbound webhooksAvailable
  • Slack and Discord deliveryAvailable
  • Versioned public APIAvailable
  • SAML and OIDC single sign-onWhen a customer asks

We will build single sign-on when a customer needs it, and not before. If that is you, tell us and it moves to the top.