Webhooks

Takibi POSTs signed JSON to your wake URL when subscribed task events happen on the boards you choose. Only enabled endpoints receive events, and only for their subscribed event types.

Payloads carry ids and transitions only. Titles and bodies never leave Takibi, so fetch the card over the API after a delivery arrives. Ignore fields you do not recognize. New additive fields never change schemaVersion.

Manage endpoints in the app with your sign-in. API keys cannot manage them.

1. Open Webhooks and choose New webhook.
2. Paste the wake URL. It must be https, with no credentials in it. Localhost and private addresses are refused.
3. Pick at least one event type. Task created is selected already.
4. Choose at least one board in Boards. New boards are never added automatically, so return here when you add one.
5. Choose Create webhook. The endpoint starts disabled. Copy the signing secret now. It verifies every delivery and is never shown again.

Creating an endpoint fires one test ping at the URL. A failed ping does not undo the creation. Fix the receiver, then use Test webhook on the detail page.

Two endpoints may share one URL. Each receives its own deliveries, and the detail page says so when it happens. Add an optional Authorization header on the detail page when your receiver wants one. It is sent with every delivery and is never shown again.

If the detail page warns about profile access, check that a worker profile holds full collection access on that board, with Tasks, Ask and Search, and task creation off.

Every delivery carries three headers. webhook-id identifies the delivery and stays stable across retries. webhook-timestamp is fresh per attempt, in unix seconds. webhook-signature holds the signature.

1. Refuse deliveries more than five minutes older or newer than now.
2. Compute HMAC-SHA256 over webhook-id.webhook-timestamp.rawBody, using the exact raw body and the signing secret as UTF-8. Base64 the result and compare it with the v1, value using a constant-time compare.
3. After a rotation the header carries two signatures for 24 hours. Accept either secret until the overlap expires.

When several endpoints share one receiver, verify each delivery against its own endpoint secret before deduping. A receiver auth value you set arrives verbatim as Authorization.

Dedupe retries on webhook-id, which equals deliveryId in the body. Dedupe side effects on eventId, which one occurrence shares across every matching endpoint. Persist both keys with the work, so a restart cannot re-run it.

The webhook tells you a card exists. It does not reserve it. Fetch the card, stop silently when it is archived, blocked or already claimed by someone else, then claim it before launching the run. A 409 names the winner, so stand down. A worker without task creation still wakes on its own moves. The claim check breaks that loop.

Takibi ships a reference receiver at tools/webhook-receiver-example/receiver.mjs. It verifies, dedupes and prints the task id with no dependencies. Copy it as the starting point for your own runner.

On the endpoint detail page, Test webhook posts a live webhook.ping to the wake URL. Testing works while the endpoint is disabled. That is the point. Verify first, then enable.

A ping never enters delivery history and never touches endpoint health. It carries endpoint and org ids, with no resource and no board. A success confirms receipt, not that the agent finished its work.

Save configuration changes before testing. A changed URL or auth value clears the last result. When a test fails, check the URL, then test again.

On the detail page, Rotate signing secret mints a new secret and shows it once. Copy it before leaving. The old secret stays valid for 24 hours while you roll the new one out, and deliveries carry both signatures during the overlap. Keep passing the old secret until the overlap expires.

Prefer one rotation per 24 hours. If you rotate again during the overlap, the middle secret stops signing and the oldest previous secret stays valid.

The Deliveries card lists the last 50 deliveries, newest first, with ids, statuses and errors only. No payloads and no secrets appear there.

Transport failures, 408, 429 and 5xx responses retry, up to six attempts in total. The waits after attempts one to five run about 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours, each with some jitter. A Retry-After header can extend a shorter wait up to one hour; it never shortens the normal backoff. Any other status parks the delivery at once.

Your receiver has 10 seconds per attempt. Headers must arrive inside that budget. Body contents do not affect acceptance, so queue slow work durably before answering 2xx. Deliveries retry and can arrive twice or out of order. Make every handler idempotent. Re-read the card and re-check eligibility before acting, so a stale event never resurrects finished work.

Disabling an endpoint pauses its queue. Queued events wait untouched and send after you enable it again. Deleting an endpoint stops retries at once and removes its delivery history with it. This cannot be undone.

One workspace holds 20 endpoints. Delete one before adding another past the cap.

• Wake URLs must be https, with no credentials in them. Localhost, private and link-local addresses are refused.
• Parked history keeps at most 500 rows per endpoint. Older parked rows go first.
• Delivered history is kept for 30 days.
• Each Test webhook press and each endpoint creation fires one ping. Pings never queue and never affect health.