Clickup Incident Runbook

ClickUp Integration Incident Response

Overview

Separate provider health, credential scope, rate exhaustion, webhook suspension, data drift, and application faults before taking recovery action.

Prerequisites

• An incident commander, severity model, affected service/Workspace inventory, and communication channel
• Read-only diagnostic capability plus audited break-glass procedures
• Known last-good deployment, queue checkpoints, and rollback targets

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

• ClickUp status, API reachability, tenant authorization, and application side effects are independent signals.
• A webhook is failing after unsuccessful or over-seven-second responses; failed events are not resent after their delivery attempts.
• At fail_count=100 a webhook is suspended; returning 401 suspends it immediately.
• 429 recovery follows the per-token reset header rather than a guessed delay.

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. Declare scope, commander, severity, affected Workspaces, write freeze, and evidence-retention boundary.
2. Check provider status and run metadata-only identity/rate probes.
3. Classify auth, plan/permission, rate, webhook health, schema, queue, deployment, or data-consistency failure.
4. Contain with write disablement, circuit breaking, queue pause, or rollback before rotating credentials.
5. Recover one lane at a time and reconcile missed or duplicate business operations from durable records.
6. Close only after verification, stakeholder communication, evidence capture, and assigned follow-up.

Approval Boundaries

Do not rotate shared tokens, reactivate webhooks, replay queues, mutate tasks, or suppress evidence without commander and owner approval.

Output

Return timeline, failure class, containment, affected Workspaces/operations, recovery evidence, reconciliation result, and follow-up owners. Include unresolved risk and the next decision deadline.

Error Handling

Examples

The example below is a redacted operator receipt; it contains no task text, member data, credential, or webhook secret.

incident=CU-207; provider=healthy; class=webhook-suspended; writes=frozen; reconcile=required; commander=assigned

Resources

• Skill-specific official documentation
• Webhook health
• Authentication
• Rate limits