customerio-advanced-troubleshooting

Customer.io Advanced Troubleshooting

Overview

Advanced debugging techniques for diagnosing complex Customer.io integration issues including API debugging, user investigation, campaign analysis, and incident response.

Prerequisites

• Access to Customer.io dashboard
• Application logs access
• Understanding of your integration architecture

Troubleshooting Framework

1. What is the expected behavior?
2. What is the actual behavior?
3. When did the issue start?
4. How many users/messages affected?
5. Is it consistent or intermittent?

Instructions

Step 1: API Debugging

Build a debug client wrapper that logs request details, measures latency, and captures error codes and response bodies for every operation.

Step 2: User Profile Investigation

Create investigation scripts that check profile existence, required attributes (email), suppression status, bounce/complaint history, and recent activity.

Step 3: Campaign Debugging

Analyze campaign status, trigger conditions, audience size, and recent send activity to find why messages aren't delivering.

Step 4: Webhook Debugging

Verify webhook signatures, parse payloads, count processed events, and capture per-event errors with timing data.

Step 5: Network Diagnostics

Run DNS resolution, TCP connectivity, TLS certificate, API latency, and rate limit checks against Customer.io endpoints.

Step 6: Follow Incident Response Runbook

Apply the appropriate runbook for the priority level: P1 (complete outage), P2 (high error rate), P3 (delivery issues), P4 (webhook failures).

For detailed implementation code and diagnostic scripts, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Diagnostic Commands

set -euo pipefail
# Check API health
curl -s "https://status.customer.io/api/v2/status.json" | jq '.status'
# Test authentication
curl -u "$CIO_SITE_ID:$CIO_API_KEY" "https://track.customer.io/api/v1/accounts"
# Check user exists
curl -u "$CIO_SITE_ID:$CIO_API_KEY" "https://track.customer.io/api/v1/customers/USER_ID"

Error Handling

Issue	Solution
User not receiving	Check suppression, segments, attributes
Events not tracked	Verify user identified first
High latency	Check network, enable connection pooling

Resources

• Customer.io Status
• Troubleshooting Guide

Next Steps

After troubleshooting, proceed to customerio-reliability-patterns for resilience.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale

See debugging implementation details for output format specifications.

Examples

Basic usage: Apply customerio advanced troubleshooting to a standard project setup with default configuration options.

Advanced scenario: Customize customerio advanced troubleshooting for production environments with multiple constraints and team-specific requirements.