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.

1. 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.

1. Audit the integration, resilience, and webhooks. Walk the remaining

checklist sections (API integration, error handling, webhook security,

monitoring).

1. Run the pre-flight script (scripts/preflight-klaviyo.sh) to validate the

status page, API auth, rate-limit headroom, and pinned SDK version.

1. Deploy, then verify the health endpoint returns healthy.
2. 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 KLAVIYOPRIVATEKEY stored in secret manager (not env file)
• [ ] Key has minimal scopes (only what the app needs)
• [ ] Webhook signing secret (KLAVIYOWEBHOOKSIGNING_SECRET) configured
• [ ] Public key (KLAVIYOPUBLICKEY) 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:

• 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.