Klaviyo Production Checklist

Overview

Complete checklist for deploying Klaviyo integrations to production, with health checks, rollback procedures, and validation against real Klaviyo API endpoints. Work the pre-deployment checklist below, run the pre-flight script, then verify the live health endpoint before declaring the deploy done.

Prerequisites

Staging environment tested and verified
Production API key with correct scopes (pk_*)
Webhook signing secret configured
Monitoring and alerting ready

Instructions

Follow these steps in order. Steps 1–2 are read-only audits of the codebase and config; steps 3–5 exercise the live API and health surface.

Audit secrets and code. Confirm the production key lives in a secret manager and no keys are hardcoded — run Grep/grep -r "pk_" src/ to catch leaks, and Read the deployment manifest to verify scopes. See the Pre-Deployment Checklist below.
Audit the integration, resilience, and webhooks. Walk the remaining checklist sections (API integration, error handling, webhook security, monitoring).
Run the pre-flight script (scripts/preflight-klaviyo.sh) to validate the status page, API auth, rate-limit headroom, and pinned SDK version.
Deploy, then verify the health endpoint returns healthy.
Keep the rollback path ready (feature flag first) in case metrics regress.

Health check, pre-flight script, and rollback code are in references/implementation.md.

Pre-Deployment Checklist

Authentication & Secrets

Production KLAVIYO_PRIVATE_KEY stored in secret manager (not env file)
Key has minimal scopes (only what the app needs)
Webhook signing secret (KLAVIYO_WEBHOOK_SIGNING_SECRET) configured
Public key (KLAVIYO_PUBLIC_KEY) set for client-side tracking (if used)
No hardcoded keys in codebase (grep -r "pk_" src/)

API Integration

All API calls use klaviyo-api SDK (not raw HTTP)
SDK version pinned in package.json (not ^ or *)
revision header set to 2024-10-15 (or current supported revision)
All profile creates use createOrUpdateProfile (upsert, not create)
Events include uniqueId for deduplication where applicable
Phone numbers validated as E.164 format (+15551234567)

Error Handling & Resilience

429 retry logic honors Retry-After header
5xx errors retried with exponential backoff
401/403 errors logged with alert (key rotation needed)
Circuit breaker or graceful degradation when Klaviyo is down
Request queue prevents exceeding 75 req/s burst limit

Webhook Security

Webhook endpoint uses HTTPS only
HMAC-SHA256 signature verification enabled
Idempotency handling (dedup by event ID)
Webhook endpoint returns 200 within 30 seconds

Monitoring

Health check endpoint includes Klaviyo connectivity test
Alert on 429 rate (>5/min = P2)
Alert on 401/403 errors (any = P1)
Alert on 5xx errors (>10/min = P1)
API latency tracked (P95 > 5s = P2)
Klaviyo status page monitored (status.klaviyo.com)

Output

Working through this skill produces:

A completed pre-deployment checklist (every box ticked, or a documented exception).
A pre-flight run that exits 0 with all four gates green (status page, API auth 200, rate-limit headroom, pinned SDK version) — see references/examples.md.
A live /health endpoint that returns healthy with sub-500ms latency and the resolved accountId.
A rehearsed rollback path (feature flag → git revert → kubectl rollout undo).

A go-live is "prod ready" only when the checklist is complete, pre-flight is green, and the health endpoint reports healthy.

Error Handling

Map each failure to the correct severity and response. Full alert-threshold table:

Alert	Condition	Severity
API Auth Failure	Any 401/403	P1 -- key may be revoked
API Unreachable	5xx > 10/min	P1 -- check status page
Rate Limited	429 > 5/min	P2 -- reduce request volume
High Latency	P95 > 5s	P2 -- check network/Klaviyo load
Webhook Signature Invalid	Any rejection	P2 -- verify signing secret

Pre-flight fails auth (403/401): the key is revoked or under-scoped. Rotate/repair before deploying — do not proceed (see Example 2 in references/examples.md).
Health endpoint degraded: Klaviyo returned 429. Back off; honor Retry-After and confirm the request queue caps at 75 req/s.
Health endpoint down: Klaviyo unreachable (5xx) — check status.klaviyo.com and trip the circuit breaker.
Metrics regress post-deploy: execute the rollback procedure, feature flag first, from references/implementation.md.

Examples

Read the full endpoint on a live integration to confirm health before sign-off:

curl -s localhost:3000/health | python3 -m json.tool
# → { "status": "healthy", "services": { "klaviyo": { "status": "healthy", "latencyMs": 142, ... } } }

Four worked runs — green pre-flight, a blocked 403, reading the health endpoint, and an instant feature-flag rollback — are in references/examples.md.

Resources

Klaviyo Status Page
API Versioning Policy
Rate Limits
Implementation code — health check, pre-flight script, rollback
Worked examples — green/failed pre-flight, health reads, rollback

Next Steps

For version upgrades, see klaviyo-upgrade-migration.