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
API Integration
Error Handling & Resilience
Webhook Security
Monitoring
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
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
Next Steps
For version upgrades, see klaviyo-upgrade-migration.
