clickup-prod-checklist

ClickUp Production Checklist

Overview

Complete checklist for deploying ClickUp API v2 integrations to production.

Pre-Launch Checklist

Authentication & Secrets

• Production API token stored in secrets manager (not env files)
• Token uses a service account, not a personal user account
• .env files in .gitignore; pre-commit hook catches pk_* patterns
• Token rotation procedure documented and tested
• OAuth client secret server-side only (never in client bundle)

Error Handling

• All API calls handle 401 (re-auth), 429 (backoff), 500 (retry)
• Exponential backoff with jitter on rate limits
• ClickUp-specific error codes parsed (ECODE field in responses)
• Circuit breaker pattern prevents cascade failures
• Graceful degradation when ClickUp API is down

Rate Limits

• Know your plan's limit (100/1K/10K req/min)
• Rate limit headers monitored (X-RateLimit-Remaining)
• Request queuing prevents burst overruns
• Caching reduces unnecessary API calls
• Webhooks replace polling where possible

Monitoring

• Health check endpoint verifies ClickUp connectivity
• API latency tracked per endpoint
• Error rate alerting (>5% triggers P2)
• Rate limit remaining alerting (<10% triggers warning)
• Structured logging with request/response metadata

Webhooks (if applicable)

• Endpoint uses HTTPS
• Responds with 200 within 30 seconds
• Idempotent processing (tracks history_items[].id)
• Async processing after immediate 200 response
• Handles ClickUp auto-disable (re-register if needed)

Production Health Verification

#!/bin/bash
# run-prod-checks.sh

echo "=== ClickUp Production Checks ==="

# 1. Auth works
echo -n "Auth: "
STATUS=$(curl -sf -o /dev/null -w "%{http_code}" \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN")
[ "$STATUS" = "200" ] && echo "PASS" || echo "FAIL ($STATUS)"

# 2. Rate limit headroom
echo -n "Rate limit: "
REMAINING=$(curl -sD - -o /dev/null \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN" 2>&1 | \
  grep -i "X-RateLimit-Remaining" | awk '{print $2}' | tr -d '\r')
echo "${REMAINING} remaining"

# 3. API latency
echo -n "Latency: "
LATENCY=$(curl -sf -o /dev/null -w "%{time_total}" \
  https://api.clickup.com/api/v2/user \
  -H "Authorization: $CLICKUP_API_TOKEN")
echo "${LATENCY}s"
[ "$(echo "$LATENCY > 2" | bc -l)" = "1" ] && echo "  WARNING: latency > 2s"

# 4. Workspace accessible
echo -n "Workspaces: "
TEAMS=$(curl -sf https://api.clickup.com/api/v2/team \
  -H "Authorization: $CLICKUP_API_TOKEN" | \
  python3 -c "import sys,json; print(len(json.load(sys.stdin)['teams']))" 2>/dev/null)
echo "${TEAMS} accessible"

# 5. ClickUp platform status
echo -n "Platform: "
curl -sf https://status.clickup.com/api/v2/summary.json | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['status']['description'])" 2>/dev/null || echo "Unknown"

echo "=== Checks Complete ==="

Rollback Procedure

# 1. If ClickUp token is compromised
# - Regenerate token in ClickUp Settings > Apps
# - Update secret in deployment platform
# - Redeploy

# 2. If integration is causing issues
# - Feature flag: disable ClickUp integration
# - Or: set CLICKUP_ENABLED=false and redeploy

# 3. If version upgrade broke things
# - Revert deployment to previous version
# - Pin API calls to specific behavior (no v3 endpoints)

Error Handling

Alert	Condition	Severity
API unreachable	0 successful requests in 5min	P1
Auth failures	Any 401 response	P1
Rate limited	X-RateLimit-Remaining = 0	P2
High latency	P95 > 3 seconds	P2
Webhook failures	3+ consecutive 5xx	P3

Resources

• ClickUp Status Page
• ClickUp Rate Limits

Next Steps

For version upgrades, see clickup-upgrade-migration.