Integration Problems¶

Common error: Failed to connect to Shopify store

Troubleshooting steps:

1. Verify Store URL Format:

   Text Only

   Correct: your-store.myshopify.com
   Incorrect: your-store.shopify.com
   Incorrect: https://your-store.myshopify.com
   

2. Check Private App Configuration:

3. Go to Shopify Admin > Settings > Apps and sales channels > Develop apps
4. Ensure app has these permissions:
   • read_customers
   • read_orders
   • read_products (optional, for product data)

5. Copy the Admin API access token exactly

6. Shopify Plan Compatibility:

1. Test Connection:
   Bash

   curl -X GET "https://your-store.myshopify.com/admin/api/2023-10/customers.json" \
        -H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN"
   

Shopify Setup Guide

Common error: Failed to authenticate with Mailchimp

Troubleshooting steps:

1. API Key Validation:

   Text Only

   Correct format: abc123def456-us1
   Missing data center: abc123def456
   Wrong separator: abc123def456_us1
   

2. Data Center Matching:

3. Check your Mailchimp URL: https://us1.admin.mailchimp.com
4. API key suffix must match: your-key-us1

5. Common data centers: us1 through us8

6. Account Status Check:

7. Login to Mailchimp dashboard
8. Check for account suspension notices

9. Verify billing status is current

10. API Key Permissions:

11. In Mailchimp, go to Account > Extras > API keys

12. Delete old key and generate new one if issues persist

13. Test API Access:

    Bash

    curl -X GET "https://us1.api.mailchimp.com/3.0/lists" \
         -u "anystring:YOUR_API_KEY"
    

Mailchimp Setup Guide

Common error: Stripe webhook verification failed

Troubleshooting steps:

1. Webhook URL Format:

   Text Only

   Correct: https://conduit.dxtra.ai/integrations/stripe/event?did=YOUR_DID&dxKey=YOUR_DXKEY
   Missing parameters: https://conduit.dxtra.ai/integrations/stripe/event
   HTTP (not HTTPS): http://conduit.dxtra.ai/integrations/stripe/event
   

2. Required Webhook Events: In Stripe Dashboard > Webhooks, enable these events:

3. customer.created
4. customer.updated
5. customer.deleted
6. customer.subscription.created (if using subscriptions)
7. customer.subscription.updated (if using subscriptions)

8. customer.subscription.deleted (if using subscriptions)

9. Webhook Signing Secret:

10. In Stripe Dashboard, click on your webhook
11. Click "Reveal" next to Signing Secret
12. Copy the whsec_... value exactly (including prefix)

13. Paste into Dxtra integration settings

14. Test Webhook Delivery:

15. In Stripe Dashboard > Webhooks > Your webhook
16. Click "Send test webhook"
17. Choose customer.created event
18. Check if Dxtra receives it (should appear in integration logs)

Stripe Setup Guide

Common error: WooCommerce API authentication failed

Troubleshooting steps:

1. REST API Enabled:
2. In WordPress Admin > WooCommerce > Settings > Advanced > REST API

3. Ensure "Enable the REST API" is checked

4. API Key Generation:

5. Go to WooCommerce > Settings > Advanced > REST API
6. Click "Add Key"
7. Set permissions to "Read/Write"

8. Copy Consumer Key and Consumer Secret

9. Permalink Structure:

10. Go to WordPress Admin > Settings > Permalinks
11. Must NOT be set to "Plain"

12. Recommended: "Post name" or "Custom Structure"

13. SSL Certificate:

14. WooCommerce REST API requires HTTPS

15. Verify SSL certificate is valid and properly configured

16. Test API Access:

    Bash

    curl -X GET "https://yourstore.com/wp-json/wc/v3/customers" \
         -u "consumer_key:consumer_secret"
    

WooCommerce Setup Guide

Error: Data validation failed during sync

Troubleshooting:

1. Check Integration Logs:
2. Look for specific record IDs that failed

3. Note the validation error messages

4. Common Data Issues:

1. Bulk Data Cleanup:
2. Export problematic records from source system
3. Clean data using spreadsheet tools
4. Re-import cleaned data
5. Trigger manual sync in Dxtra

Issue: Sync takes very long or doesn't complete

Optimization steps:

1. Large Dataset Handling:
2. Syncs with many records may take several hours
3. Progress is shown in integration logs

4. Don't cancel during initial sync

5. Sync Time Estimates:

   Text Only

   ~1,000 records: 5-10 minutes
   ~10,000 records: 30-60 minutes
   ~100,000+ records: 2-6 hours
   

6. Performance Troubleshooting:

7. Check network connectivity stability
8. Verify third-party service isn't experiencing issues
9. Consider syncing during off-peak hours for large datasets

Error: Rate limit exceeded, sync paused

Understanding Rate Limits:

Resolution: - Rate limits are handled automatically with backoff - Sync will resume when limit resets - No manual action needed for temporary rate limiting - If persistent, contact support for optimization

Issue: Integration fails in corporate/enterprise environments

Required Network Access:

Dxtra Endpoints (must be accessible):

https://conduit.dxtra.ai:443
https://auth.dxtra.ai:443
https://api.dxtra.ai:443

Third-Party Endpoints (by service):

Shopify:      *.myshopify.com:443
Mailchimp:    *.api.mailchimp.com:443
Stripe:       api.stripe.com:443
WooCommerce:  Your store domain:443

Network Requirements: - Outbound HTTPS (port 443) access - No SSL inspection on API endpoints - Support for TLS 1.2 or higher - No proxy authentication required for API calls

Issue: Cannot resolve Dxtra or third-party service domains

Diagnosis:

nslookup conduit.dxtra.ai
nslookup api.dxtra.ai
nslookup your-store.myshopify.com

Solutions: - Use public DNS servers (8.8.8.8, 1.1.1.1) for testing - Check corporate DNS forwarding - Verify no DNS filtering blocking required domains

Symptoms: Integration was working but suddenly stopped

Investigation steps:

1. Check Credential Status:
2. Login to third-party service dashboard
3. Verify account is active and in good standing

4. Check for password or API key changes

5. Service-Specific Checks:

Shopify: - Private app still exists and is enabled - API permissions haven't been changed - Store hasn't been transferred to different account

Mailchimp: - Account billing is current - API key hasn't been regenerated - Account hasn't been suspended for policy violations

Stripe: - Webhook endpoint is still active - API keys haven't been rotated - Account is in good standing with Stripe

1. Credential Refresh:
2. Generate new API keys/tokens in the third-party service
3. Update credentials in Dxtra Dashboard > Integrations
4. Test connection after updating

Error: Insufficient permissions for requested operation

Resolution:

1. Review Required Permissions:
2. Check integration documentation for minimum permissions
3. Compare with current permissions in third-party service

4. Upgrade permissions as needed

5. Permission Requirements by Service:

Accessing Logs: 1. Dashboard > Integrations > Select integration 2. Click "View Logs" or "Integration Details" 3. Look for error patterns and timestamps

Log Analysis Tips:

• Repeated error messages: Indicates systematic issue
• Specific record IDs that fail: Data quality issues
• Network timeouts: Connectivity problems
• Authentication errors: Credential issues
• Rate limiting messages: API quota issues

Common Log Patterns:

API Connection Test:

Test integration endpoints directly:

curl -X POST "https://conduit.dxtra.ai/integrations/shopify/event?did=YOUR_DID&dxKey=YOUR_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Shopify-Hmac-Sha256: test" \
     -H "X-Shopify-Topic: customers/create" \
     -H "X-Shopify-Shop-Domain: test.myshopify.com" \
     -d '{"test": "webhook"}'

curl -X POST "https://conduit.dxtra.ai/integrations/stripe/event?did=YOUR_DID&dxKey=YOUR_KEY" \
     -H "Content-Type: application/json" \
     -H "Stripe-Signature: test" \
     -d '{"test": "webhook"}'

Expected Responses: - 200 OK: Integration is working (may reject invalid signatures) - 401 Unauthorized: Check DID and dxKey parameters - 403 Forbidden: Invalid signature (expected for test requests) - 500 Server Error: Service issue, check system status

When to Reset: - Multiple troubleshooting attempts failed - Credentials have been changed in third-party service - Suspect configuration corruption

Reset Process:

1. Document Current Settings:
2. Take screenshots of current configuration
3. Note any custom field mappings

4. Record sync frequency and preferences

5. Disconnect Integration:

6. Dashboard > Integrations > Select integration
7. Click "Disconnect" or "Remove"

8. Confirm data will be preserved

9. Reconnect Integration:

10. Click "Add Integration"
11. Follow setup wizard with fresh credentials
12. Reconfigure any custom settings

13. Test with small data sync first

14. Verify Reset Success:

15. Check connection status (should be active)
16. Monitor first sync completion
17. Verify data appears correctly in Dxtra