Integration Specialist

AG-INTEGRATIONS handles all third-party service integrations, from payment processors and authentication providers to webhooks and data synchronization with external APIs.

Capabilities

• API Client Implementation: Stripe, Twilio, SendGrid, AWS, Google, and other services
• Webhook Handling: Signature validation, idempotency, event processing
• Authentication Providers: Auth0, OAuth (Google, GitHub, Facebook), AWS Cognito
• Payment Processing: Stripe, Square, PayPal with webhook handling
• Email Delivery: SendGrid, Mailgun, AWS SES integrations
• Error Handling & Retry Logic: Exponential backoff, rate limiting, graceful degradation
• Health Checks & Monitoring: External service health tracking

When to Use

Use AG-INTEGRATIONS when:

• Integrating third-party APIs (Stripe, Twilio, SendGrid, etc.)
• Setting up authentication providers (Auth0, Google OAuth)
• Implementing webhook receivers and handlers
• Building payment processing flows
• Handling external service failures gracefully
• Implementing retry logic with exponential backoff
• Setting up health monitoring for external services

How It Works

1. Context Loading: Reads expertise file and existing integrations
2. Service Research: Reviews documentation, pricing, rate limits, authentication
3. Client Implementation: Creates API client with proper authentication
4. Error Handling: Implements comprehensive error handling and retry logic
5. Webhook Setup: Validates signatures, implements idempotency
6. Testing: Creates integration tests with mocked external services
7. Monitoring: Sets up health checks and alerts

Example

Copy# Via /babysit
/agileflow:babysit
> "I need to add Stripe payments with webhook handling"
 
# AG-INTEGRATIONS will:
# 1. Research Stripe API and webhook events
# 2. Implement Stripe API client with authentication
# 3. Create webhook receiver with signature validation
# 4. Implement retry logic for failed charges
# 5. Create integration tests (mocked Stripe)
# 6. Document setup and webhook events

Key Behaviors

• Never Hardcodes Secrets: Always uses environment variables for API keys
• Validates Webhooks: Signature validation is mandatory (prevents spoofing)
• Handles All Errors: Network, timeout, rate limit, and service errors
• Implements Retry Logic: Exponential backoff with jitter
• Secure Logging: Never logs credentials or sensitive data
• Graceful Degradation: Provides fallback if external service unavailable

Tools Available

• Read, Write, Edit, Bash, Glob, Grep
• Access to Session Harness for verification

Common Integrations

Payment Processing:

• Stripe - Payments, subscriptions, payouts
• Square - Point-of-sale
• PayPal - Payments, subscriptions

Authentication:

• Auth0 - Enterprise authentication
• Google OAuth - Social login
• GitHub OAuth - Developer login

Email Delivery:

• SendGrid - Transactional email
• Mailgun - Email delivery
• AWS SES - Cost-effective email

SMS/Messaging:

• Twilio - SMS, voice, messaging
• AWS SNS - Message delivery
• Firebase Cloud Messaging - Push notifications

File Storage:

• AWS S3 - Cloud storage
• Google Cloud Storage - Cloud storage
• Azure Blob Storage - Cloud storage

Integration Pattern

Copy// 1. Create client with auth
const client = new StripeClient(process.env.STRIPE_API_KEY);
 
// 2. Make authenticated request
const payment = await client.payments.create({
  amount: 10000,
  currency: 'usd',
});
 
// 3. Handle errors
if (payment.error) {
  logger.error('Payment failed', {
    error: payment.error,
    // Never log sensitive data
  });
  // Implement retry or fallback
}

Webhook Security

Critical Requirements:

• Validate webhook signature (prevent spoofing)
• Respond with 200 OK immediately (confirm receipt)
• Process asynchronously (don't block response)
• Handle duplicates (webhooks may be retried)

Error Handling Strategy

• Identify retriable errors (network, timeout, 5xx)
• Implement exponential backoff with jitter
• Set maximum retry count
• Log failures and alert if persistent
• Implement graceful degradation

Quality Checklist

Before marking integration work complete:

• Service authentication working
• API calls tested and working
• All errors handled (network, timeout, rate limit)
• Retry logic with exponential backoff implemented
• Webhooks validated (signature check)
• Webhooks idempotent (handle duplicates)
• API keys in environment variables (never hardcoded)
• Error logging doesn't expose secrets
• Integration tests cover happy path + error scenarios
• Documentation complete (setup, authentication, configuration)
• Health check or monitoring in place
• Tests passing with test_status: "passing"

Related Agents

• AG-API - Service layer integration and endpoints
• AG-SECURITY - Secure credential management
• AG-MONITORING - Health checks and alerting

Coordination Messages

AG-INTEGRATIONS coordinates with other teams:

Copy{
  "ts": "2025-10-21T10:00:00Z",
  "from": "AG-INTEGRATIONS",
  "type": "status",
  "story": "US-0040",
  "text": "Stripe integration ready, AG-API can now implement payment endpoint"
}

Slash Commands

• /agileflow:research:ask TOPIC=... - Research service best practices
• /agileflow:ai-code-review - Review integration code for security
• /agileflow:adr-new - Document integration choice decisions
• /agileflow:tech-debt - Document missing error handling
• /agileflow:status STORY=... STATUS=... - Update story status