ClickUp Signed Webhook Operations
Overview
Treat webhooks as signed, user-owned change signals that need durable processing and reconciliation. Assume delivery can duplicate, arrive late, or stop after ownership changes.
Prerequisites
- A public HTTPS endpoint capable of retaining raw request bytes
- A secret manager, durable queue/idempotency store, and Workspace allow-list
- An authorized user owner for the webhook plus monitoring and reconciliation
Tool Discipline
Use Read, Glob, and Grep to inspect the repository, adapters, configuration names, tests, and evidence. Use WebFetch only for current official ClickUp documentation. Use Write or Edit after confirming the target file, Workspace boundary, and requested mode.
Current Contract
- Webhook creation returns a unique secret; verify raw-body HMAC-SHA256 against hexadecimal
X-Signature. - Registrations are tied to the creating user and can stop triggering when that user is disabled or loses hierarchy access.
- Use
webhook_id:history_item_idas the documented idempotency key when a history item exists; handle events without one deliberately. - Responses over seven seconds or unsuccessful responses are failures; ClickUp attempts delivery up to five times, does not resend the failed event later, suspends at
fail_count=100, and a 401 suspends immediately.
Authentication
Use a personal token only for accountable individual/testing work or OAuth Authorization Code for a user-facing integration. Inject the token server-side through a governed secret reference, send it in Authorization, verify authorized Workspace IDs, and never print the token, OAuth client secret, or webhook secret.
Instructions
- Choose the narrowest location and explicit event set; inventory duplicate registrations before creation.
- Register only after endpoint ownership, HTTPS, secret storage, and rollback approval are confirmed.
- Capture raw bytes, look up the per-webhook secret, verify HMAC in constant time, then parse/validate JSON.
- Persist idempotency and enqueue before a fast success response; process business effects asynchronously.
- Monitor status/fail count, latency, duplicates, dead letters, and owner eligibility.
- Run reconciliation reads for delivery gaps and rotate/re-register safely when ownership changes.
Approval Boundaries
Require approval before creating, broadening, suspending/reactivating, rotating, or deleting production webhooks and before replaying business effects.
Output
Return the registered scope, credential-storage identifier, HMAC verification and idempotency test results, delivery health, queue result, reconciliation status, and rollback.
Error Handling
| Condition | Response |
|---|---|
| Signature invalid | Reject before parsing and record content-free evidence. |
| Handler cannot persist within deadline | Return failure deliberately and repair capacity; do not acknowledge lost work. |
| Webhook suspended | Contain, diagnose fail count/401 behavior, and reactivate only after approval. |
| History item is absent | Use a documented event-specific fallback key and reconciliation. |
Examples
The example below is a redacted operator receipt; it contains no task text, member data, credential, or webhook secret.
events=taskUpdated,taskDeleted; hmac=pass; ack=82ms; duplicate=ignored; fail-count=0; reconcile=pass