Webhook Configuration Guide

Webhook Configuration Guide

Configure webhooks to receive instant notifications when shipping events occur in your AtoShip account.

What Are Webhooks?

Definition: Webhooks are automated messages sent from AtoShip to your server when specific events occur.

Benefits:

• Real-time notifications
• Automated workflows
• Reduce polling
• Instant updates

Available Events

Shipping Events:

Order Events:

Creating a Webhook

Step-by-Step:

1. Go to Settings → Webhooks
2. Click "Add Webhook"
3. Enter endpoint URL
4. Select events to subscribe
5. Save configuration

Endpoint Requirements

Your Server Must:

• Accept POST requests
• Use HTTPS (required)
• Respond within 30 seconds
• Return 2xx status code

Webhook Payload

Example Payload:

{
  "event": "label.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "label_id": "lbl_abc123",
    "tracking_number": "9400111899223",
    "carrier": "USPS",
    "service": "Priority Mail",
    "order_id": "ord_xyz789"
  }
}

Verifying Webhooks

Signature Verification:

X-AtoShip-Signature: sha256=abc123...

Verify in Code:

const crypto = require('crypto');
const signature = req.headers['x-atoship-signature'];
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');
const valid = signature === expected;

Retry Policy

Failed Deliveries:

• Retry up to 5 times
• Exponential backoff
• 1min → 5min → 30min → 2hr → 24hr

Testing Webhooks

Test Methods:

1. Use webhook testing tools
2. Send test event from dashboard
3. Check webhook logs
4. Verify payload received

Common Use Cases

Automation Examples:

• Update order management system
• Send custom notifications
• Trigger inventory updates
• Log shipping data
• Alert on exceptions

Tracking Updates

Tracking Event Flow:

Accepted → In Transit →
Out for Delivery → Delivered

Exception Events:

• Delivery attempted
• Address issue
• Package held
• Returned to sender

Multi-Endpoint Setup

Advanced Configuration:

• Different URLs per event
• Environment-specific endpoints
• Backup endpoints

Error Handling

Best Practices:

1. Log all received webhooks
2. Process asynchronously
3. Return 200 immediately
4. Handle duplicates
5. Verify signatures

Webhook Logs

View History:

• All sent webhooks
• Response codes
• Retry attempts
• Payload details

Security Considerations

Protect Your Endpoint:

• Verify signatures always
• Use HTTPS only
• Whitelist AtoShip IPs
• Don't expose secrets

IP Allowlist

AtoShip IPs:

52.xx.xx.xx
54.xx.xx.xx
(Check dashboard for current list)

Troubleshooting

Not Receiving Webhooks:

1. Verify endpoint URL
2. Check HTTPS certificate
3. Confirm firewall rules
4. Test endpoint access
5. Review webhook logs

Duplicate Events:

• Implement idempotency
• Track event IDs
• Skip processed events

Disabling Webhooks

To Pause or Delete:

1. Settings → Webhooks
2. Select webhook
3. Toggle off or delete
4. Confirm action

Rate Limits

Delivery Limits:

• 1000 events/minute max
• Per-endpoint limits
• Burst handling