Send board events to your endpoint

A webhook sends a signed HTTPS request to your server whenever something changes on one board: a task is created, a list is renamed, a checklist item is completed. Your server can then update another system, post a chat message, or start a build.

Kanroo webhooks are stricter than many others. Before Kanroo sends any board event, your endpoint must prove that it belongs to you. Every request is signed, and a webhook stops on its own when your endpoint keeps failing or when you lose access to the board. This page explains each step.

Webhooks are available on every Kanroo Cloud plan, see Plans and limits. A self-hosted deployment has them only with the Enterprise Edition.

What you need

• A public HTTPS endpoint on port 443. Plain HTTP, other ports, and private or internal addresses are not accepted. The URL may have a query string, but no user name, password, or fragment.
• No redirects. Kanroo never follows a redirect. A redirect response counts as a failure.
• Access to the board. You need at least viewer access to an active board. Archived boards cannot be selected.
• Personal sign-in. Webhooks are protected personal settings. Sign in with your email address and the one-time code, see Personal sign-in and SSO sign-in. Personal API keys cannot manage webhooks.

Each webhook belongs to you alone. Board owners and organization administrators do not see or manage it. You can have at most five webhooks.

Set up a webhook

Open Personal settings from the account menu at the bottom of the sidebar, then the Webhooks tab, and choose Create Webhook.

(enlarge)

1. Enter a name and the endpoint URL (box 1).
2. Choose the board (box 2).
3. Select at least one event in the groups (box 4). Select all (box 3) selects every event that exists today; events added later are never selected automatically.
4. Choose Create Webhook (box 5).

(enlarge)

1. Kanroo shows the signing secret once (box 1). Copy it into your server’s configuration. Kanroo cannot show it again.
2. Confirm that you saved it (box 2) and choose Done (box 3).

(enlarge)

1. The webhook now shows Pending verification (box 1). It sends no board events yet.
2. Prepare your endpoint as described in the next section, then choose Verify in the webhook’s menu (⋯, box 2).

The board cannot be changed after creation. To watch another board, create a second webhook.

Verify your endpoint

Verification proves that the endpoint is yours and ready. Kanroo sends one request with the event type webhook.verification and a random challenge:

{
    "id": "4c8b7d8e-1f0a-4a5e-9a51-7b2f3c9e0d11",
    "type": "webhook.verification",
    "version": 1,
    "occurredAt": "2026-10-04T09:30:00.000Z",
    "organizationId": "…",
    "board": { "id": "…", "name": "Product roadmap" },
    "actor": { "userId": "…", "displayName": "Mira Author" },
    "data": { "challenge": "x8Jq2…" }
}

Your endpoint must answer with status 2xx and a JSON body that contains exactly the same challenge:

{ "challenge": "x8Jq2…" }

When the answer matches, the webhook becomes Active and starts sending board events. When it does not match, the webhook stays Pending verification; fix the endpoint and choose Verify again. Every verification uses a new challenge and is not retried automatically. You can verify a webhook at most five times per hour.

The delivery log (see below) shows the request Kanroo sent and the response it received, which helps to find the problem.

Check the signature

Every request is signed according to Standard Webhooks. Each request carries three headers:

Header	Content
webhook-id	The stable delivery ID. A retry or a redelivery uses the same ID.
webhook-timestamp	The time of this attempt, in seconds since 1970.
webhook-signature	One or more signatures, for example v1,K5oZfz…

Use an official Standard Webhooks library for your language and pass it the secret that starts with whsec_. The library checks the signature over the ID, the timestamp, and the exact raw body. Check the raw body as received; do not parse and re-serialize the JSON first. Reject a request whose signature does not match.

Choose Rotate secret in the webhook’s menu when the secret may have leaked. Kanroo shows the new secret once. For the next 24 hours, every request carries signatures for the new and the previous secret, so you can update your server without losing events. After 24 hours, only the new secret signs.

What a request contains

Every request is a JSON POST with these top-level fields:

Field	Content
id	The ID of the event. The same change sent to two of your webhooks has the same id.
type	The event type, for example task.moved
version	Always 1
occurredAt	When the change happened (UTC)
organizationId	The organization of the board
board	ID and name of the board; a Page event has space instead
actor	The user who made the change, or null for a change by Kanroo itself
data	The changed object, and for updates and moves the previous and new values

A change made with a personal API key names the key’s owner as the actor. Tasks created from an email intake have no actor and never contain the sender’s address.

Deduplicate with webhook-id. Kanroo delivers each event at least once. In rare cases, such as a server restart right after your endpoint answered, the same delivery can arrive twice. Use the webhook-id header to recognize it, not the body id.

Order. Each webhook sends one request at a time and in order. A delivery that is waiting for a retry holds back later deliveries of the same webhook. Use occurredAt and the version of the changed object when the exact order matters.

Answer quickly

Answer with any 2xx status within three seconds; do the real work afterwards. Kanroo reads at most 64 KiB of the answer and keeps at most 4 KiB of it for the delivery log. A request body can be up to 1 MiB.

Retries

Kanroo tries an event up to five times: immediately, then after 1, 5, 15, and 30 minutes, with a small random delay. A Retry-After header can delay a retry by at most two more hours.

Answer of your endpoint	What Kanroo does
Any 2xx	Success
No answer, network error, or timeout	Retry
408, 425, 429, or any 5xx	Retry
Any redirect (3xx)	Stop; the delivery failed
Any other 4xx	Stop after the first attempt; the delivery failed

When the fifth attempt also fails, the delivery has failed for good.

Statuses

Status	Meaning	What you can do
Pending verification	The current URL is not verified. No board events are sent.	Verify
Active	Events are sent.	Send test, Pause, edit, rotate the secret
Paused	You stopped the webhook. Waiting events were cancelled; new changes are not recorded.	Resume
Disabled	Kanroo stopped the webhook, see the reason on the status.	Fix the endpoint, then Verify
Board access revoked	You lost access to the board. The webhook cannot be used again.	Delete

Hover over or focus a status with an info icon to read its reason. While a webhook is paused or disabled, changes on the board are not recorded for it and are not sent later.

Why a webhook stops

• Three failed deliveries in a row. After three deliveries that failed for good, Kanroo disables the webhook and sends you one email. One successful delivery resets the count. Tests, verifications, and redeliveries do not count.
• Too many waiting deliveries. When 500 deliveries are waiting for one webhook, Kanroo disables it and sends you one email.
• Lost board access. When your access to the board drops below viewer, the webhook changes to Board access revoked and sends nothing more, even if your access returns later. You receive one email. Delete the webhook and create a new one if you need it again.
• Old SSO sign-in. If your organization requires single sign-on (SSO), Kanroo sends a delivery only if you signed in through SSO within the last 24 hours. Otherwise it skips that delivery and the webhook stays Active. Skipped deliveries are not sent again after you sign in; later events are delivered normally.
• The board was deleted. All webhooks of the board are removed, and you receive one email.

An archived board keeps its webhooks; changes are blocked while it is archived. Archiving or restoring a board sends no event.

To start a Disabled webhook again, fix your endpoint and choose Verify. A successful verification makes it Active and resets the failure count.

Change a webhook

• Name and events can be changed at any time. The change applies to new events only.
• A new URL must be verified again. Kanroo cancels waiting deliveries for the old URL and sets the webhook to Pending verification. The secret stays the same.
• Pause stops the webhook and cancels waiting deliveries. Resume starts it again without a new verification, as long as the URL is unchanged.
• Delete removes the webhook with its secret and its delivery log immediately.

Test and inspect deliveries

• Send test sends a webhook.test request with empty data to an active webhook. It is not retried and does not affect the failure count.
• Delivery log lists the deliveries of the last 14 days by default, newest first. Filter by event or result, and open a row to see the exact request body, every attempt with its request headers, the HTTP status, and the start of the answer.
• Redeliver sends one delivery again with its original body and delivery ID, signed with the current secret. It is available for board events and tests of an active webhook, is not retried, and does not affect the failure count.

Verification, tests, and redeliveries together are limited to 20 per hour across all your webhooks.

Events

Select the events you need. There is no wildcard.

Group	Events
Tasks	task.created, task.updated, task.moved, task.deleted, task.archived, task.restored, task.recurred, task.assignee_added, task.assignee_removed, task.label_added, task.label_removed, task.attachment_added, task.attachment_removed
Lists	list.created, list.renamed, list.moved, list.work_in_progress_limit_changed, list.color_changed, list.deleted
Comments	comment.created, comment.updated, comment.deleted
Checklists	checklist.created, checklist.renamed, checklist.moved, checklist.deleted
Checklist items	checklist.item_added, checklist.item_updated, checklist.item_completed, checklist.item_uncompleted, checklist.item_moved, checklist.item_removed
Pages	page.created, page.updated, page.moved, page.archived, page.restored, page.deleted

Good to know:

• task.updated covers the title, description, priority, and due date. Assignees, labels, attachments, moves, comments, and checklists have their own events.
• There is no “completed” event for tasks. A task is done when it moves into the board’s done list, which sends task.moved.
• task.recurred means Kanroo reset a finished repeating task: it moved the task from the done list back to the top of the first list and set its next due date. The event has no actor.
• Deleting a list, task, or checklist sends one event for the deleted object only, not one for each object inside it.
• Page events belong to a space, not to a board. A webhook receives them for the spaces of its board’s organization that you can view.

When something goes wrong

Verification keeps failing. Open the delivery log and the newest verification. Check that your endpoint answered with 2xx within three seconds, that it did not redirect, and that the answer is JSON with exactly the received challenge.

Every request is rejected by my signature check. Make sure your server checks the raw body and uses the full secret including whsec_. After a rotation, use the new secret.

No events arrive. Check that the webhook is Active, that the events are selected, and that the change happened on the selected board. A paused or disabled webhook records no events.

The webhook shows Disabled. Hover over the status to see whether failures or too many waiting deliveries caused it. Fix the endpoint, then choose Verify.