---

name: clickup-webhooks-events description: >- Register, verify, process, monitor, and reconcile ClickUp webhooks with raw-body HMAC, durable idempotency, fast acknowledgment, and gap recovery. Use when building event-driven ClickUp integrations. Trigger with "ClickUp webhook", "verify X-Signature", or "ClickUp events". argument-hint: "[workspace-id] [endpoint-url] [plan|apply]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.8.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags:

• saas
• clickup
• webhooks model: inherit effort: high compatibility: Designed for Claude Code; registration requires authorized ClickUp access and public HTTPS ingress

---

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_id as 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

1. Choose the narrowest location and explicit event set; inventory duplicate registrations before creation.
2. Register only after endpoint ownership, HTTPS, secret storage, and rollback approval are confirmed.
3. Capture raw bytes, look up the per-webhook secret, verify HMAC in constant time, then parse/validate JSON.
4. Persist idempotency and enqueue before a fast success response; process business effects asynchronously.
5. Monitor status/fail count, latency, duplicates, dead letters, and owner eligibility.
6. 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

Resources

• Skill-specific official documentation
• Webhooks
• Authentication
• Rate limits