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.

If you subscribe to both Task created and Assignment, creating an assigned task sends two deliveries with different event IDs, unless the endpoint collapses several changes into one delivery. Subscribe only to Assignment for a worker that starts on assignment, or use an atomic check in your queue to prevent starting the same task twice.

Payloads carry ids and transitions only. The webhook does not include task titles or bodies. Fetch those through the API with an authorized key after a delivery arrives. Deliveries also carry actor (kind of human, profile or system, with the acting profileId or null), the holder transition in assignee: {from, to} on assignment events, and a post-change snapshot with assignee, status, blocked and archived — ids and flags only, never titles or bodies. Ignore fields you do not recognize. New additive fields never change schemaVersion.

Every endpoint can narrow its own deliveries. Filters are opt-in: an empty filter keeps today's behavior, and each endpoint filters independently, so a worker endpoint and a watcher endpoint can share a board without sharing noise.

• Only tasks held by — deliver only when the task's holder after the change is this profile. The previous holder gets no release notice, and unassigned tasks never match. When the profile is deleted, the filter matches nothing until you pick another profile — the stored id is kept, never cleared to unfiltered. When the profile is disabled, the filter matches nothing only while it stays disabled; re-enabling delivers again.
• Only moves to — deliver status moves only when the task lands in one of the chosen columns. Other event types always pass.
• Owned by plus Skip the owner's own writes — drop deliveries for changes the owner profile made itself. The rule compares actor to owner, never human to bot, so a handoff from one profile to another still delivers.
• Collapse one action into a single delivery — when one action yields two or more matched changes, send one delivery instead of one per change. The envelope event is the first match, and transition fields such as assignee: {from, to} appear only inside the changes array. A single matched change keeps the per-change shape, with assignee: {from, to} at the top level. changes lists the matches after subscriptions and filters — not every change the action produced.

Two setups cover most receivers. A worker subscribes to Assignment only, filters to its own profile, and skips its own writes — it wakes only when a task lands with it. A watcher subscribes to Assignment with no assignee filter plus Status moves to Review and Done, and selects every board — membership is explicit and new boards are never added automatically — it sees every handoff and every finish, and nothing else.

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. Give it a Name when you run several receivers of one kind. The list shows the name instead of the bare URL.
4. Pick at least one event type. Task created is selected already.
5. Choose at least one board in Boards. Scroll the list or use Search all boards to find the others. New boards are not added automatically; edit the webhook when you want to include another board.
6. Choose Create webhook. The endpoint starts disabled. Copy the signing secret now. It verifies every delivery and is never shown again.

If your receiver issued its own signing secret, paste it into Signing secret instead of taking a generated one — see bring your own secret.

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. Open the endpoint afterwards to narrow its deliveries — see filter deliveries.

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. On endpoints with a pasted whsec_ secret, derive the key by base64-decoding the secret after the whsec_ prefix. 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 IDs with the queued work to detect repeated deliveries after a restart. External actions need their own duplicate protection: a process can stop after publishing but before recording success.

Fetch the current task before starting work. Skip archived, blocked or finished tasks, and tasks assigned to another Profile. The exception is task.wake_due: that task is blocked on purpose. Resume it only if your worker still holds it, its wakeEpoch equals the delivery's epoch, and its wakeAt has passed; then unblock it in the run you start. Otherwise ignore the delivery. If your worker picks up unassigned tasks, claim the task first and handle a 409 by checking its current state. If the task is already assigned to your worker, check that it is still To do before starting. Record which task runs you have started, and filter event causes and task states so the worker does not launch itself again when it claims a task or changes its status.

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. You can test while the endpoint is disabled. Save the signing secret in your receiver, get a successful test, then enable deliveries.

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. If a test returns 401, check the signing secret and any Authorization header your receiver requires. For connection errors, check that the HTTPS URL is publicly reachable. Test again after fixing the cause.

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. Update your receiver to accept the new secret before 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.

Endpoints with a pasted secret cannot rotate here — pasted secrets rotate at the Grok trigger. See bring your own secret.

Some receivers issue their own signing secret. A Grok trigger, for example, shows a whsec_… secret that deliveries must verify against. Paste that secret into Takibi so our signatures verify at the trigger: fill Signing secret when you create the endpoint. On the detail page later, choose Paste a whsec_ secret instead under Signing secret on a generated-secret endpoint, or Replace once a pasted secret is installed. Only whsec_ secrets are accepted; anything else is refused.

A pasted secret is never shown again. The detail page shows a whsec_… fingerprint ending in the secret's last four characters, so you can confirm which secret is installed.

Setting a pasted secret is a hard cutover with no 24-hour overlap: deliveries signed with the old secret stop verifying at once, on the very next delivery. Prefer setting the new secret while the endpoint is disabled, then test and enable. Rotation stays disabled on pasted-secret endpoints — when the trigger rotates, paste the new secret here.

Changing the wake URL on a pasted-secret endpoint resets the secret: the Grok secret belongs to the old trigger, so a fresh generated secret is minted and shown once. Save it or paste the new trigger's secret afterwards.

If a Grok trigger answers a test with 401, the pasted secret does not match the trigger's current secret — copy it again from the trigger and re-paste. If the trigger also requires an Authorization header, set it on the detail page.

The Deliveries card lists the last 50 deliveries, newest first, with ids, statuses and errors only. No payloads and no secrets appear there. A failed delivery shows a short redacted excerpt of your receiver's response body when it sent one, so a 400 usually tells you what it rejected; test pings never show excerpts.

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. Replay requeues one parked delivery; Replay parked requeues every parked delivery on the endpoint, oldest first and staggered over time so one backlog cannot starve the sender. Limit it to recent deliveries when older events went stale — every replay wakes agents again.

Your receiver has 10 seconds per attempt. Headers must arrive inside that budget. Body contents do not affect acceptance — the excerpt is display-only — 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 task and re-check eligibility before acting, so a stale event never resurrects finished work.

Disabling an endpoint pauses its queue. Previously queued events wait and send after you enable it again. Changes made while the endpoint is disabled do not queue new deliveries. 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.