Webhooks

Webhooks are HTTP callbacks that notify your application when events occur in your Atoship account. Instead of polling our API for updates, webhooks push data to your server in real-time.

All webhook payloads follow a consistent format with the event type, timestamp, and relevant data.

{
  "id": "evt_abc123def456",
  "object": "Event",
  "type": "tracking.delivered",
  "created_at": "2025-01-12T14:30:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "tracking_number": "9400111899223033005436",
      "carrier": "USPS",
      "status": "delivered",
      "status_detail": "Package delivered to recipient",
      "delivered_at": "2025-01-12T14:28:00.000Z",
      "location": {
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001"
      }
    },
    "previous_attributes": {
      "status": "out_for_delivery"
    }
  }
}

Each webhook includes an X-Atoship-Signature header containing an HMAC-SHA256 signature of the payload using your webhook secret.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Usage in your webhook handler
app.post('/webhooks/atoship', (req, res) => {
  const signature = req.headers['x-atoship-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  const event = req.body;
  console.log('Received event:', event.type);

  res.status(200).send('OK');
});

If your endpoint returns a non-2xx status code or times out, we'll retry the webhook delivery.