Webhooks let another system react to what happens on a board. When a subscribed event occurs, KanbanWP sends an HTTP POST with a JSON body to the URL you provide.
Events
| Event key | Sent when |
|---|---|
task_created | A task is created, including tasks made by a form, a WooCommerce order or product, a WordPress post or an MCP agent. |
task_updated | A task’s fields change. |
task_moved | A task moves to another stage. |
task_deleted | A task is deleted. |
comment_added | A comment is added to a task. |
board_created | A board is created. |
A webhook belongs to one board and listens for events on that board. You can subscribe to specific events, or to all of them (*).
Site admins can also choose All boards (site-wide) as the board. A site-wide webhook gets events from every board, including board_created. A new board has no webhooks of its own when it is created, so board_created only reaches site-wide webhooks. Site-wide webhooks are available from version 1.0.4. Through the REST API, they live under board ID 0: /boards/0/webhooks.
Set up a webhook
- Go to KanbanWP > Webhooks. You need permission to manage the board.
- Under Add Webhook, choose the Board, or All boards (site-wide) if you are a site admin.
- Enter the Payload URL. It must be a valid public address, ideally HTTPS. KanbanWP doesn’t send webhooks to private, loopback or link-local addresses, such as
localhostor an address on your local network. - Tick the Events you want. Leaving all boxes unticked subscribes to every event.
- Keep Active ticked and click Add Webhook.
- Copy the signing secret from the notice at the top of the page. It is shown only this once.
The Existing Webhooks table lists each hook with its board, URL, events and active state, plus Edit and Delete links. You can switch a hook off with Active without deleting it. To move a hook to another board, or to All boards (site-wide), click Edit, change the Board and save.
The request
Each delivery is a POST with Content-Type: application/json and these headers:
X-KanbanWP-Event: the event key, such astask_moved.X-KanbanWP-Signature:sha256=followed by a hex HMAC.X-KanbanWP-Delivery: a unique delivery ID.
The body looks like this:
{
"event": "task_moved",
"site": "https://example.com",
"board_id": 3,
"task_id": 41,
"data": {
"task": { "id": 41, "title": "Draft launch post" },
"old_stage_id": 12,
"new_stage_id": 13
},
"sent_at": "2026-10-13T09:30:00+00:00"
}
The data object depends on the event. Task events include the task. task_updated adds changes, task_moved adds the old and new stage IDs, comment_added includes the comment, and board_created includes the board. The payload can be changed by developers with the kanbanwp_webhook_payload filter.
Verify the signature
Each webhook has its own secret, generated when the webhook is created. The signature is an HMAC-SHA256 of the raw request body, keyed with that secret. Compute it on your side and compare it with the header using a constant-time comparison.
$expected = 'sha256=' . hash_hmac( 'sha256', $raw_body, 'YOUR_WEBHOOK_SECRET' );
$valid = hash_equals( $expected, $_SERVER['HTTP_X_KANBANWP_SIGNATURE'] );
The secret is shown once, when the webhook is created: in a notice on the KanbanWP > Webhooks screen, or in the response when you create the webhook through the REST API. After that, listing, reading or updating the webhook through the REST API leaves the secret out, and the admin screen shows only its first eight characters. If you lose the secret, edit the webhook, tick Rotate secret and save. The new secret is shown once in the same way, and your receiver must use it from then on. The full-data export leaves webhook secrets out.
Delivery behavior
- Requests are sent in the background with a five second timeout. KanbanWP does not wait for your reply and does not retry.
- If the request cannot be sent at all, a failure entry is added to the board’s activity log. A slow or error response from your server is not recorded.
- Respond quickly, and do heavy work after you answer.
Developer access
Webhooks can also be listed, created, updated and deleted through the REST API, which is handy for scripted setup. See the REST API.