Webhooks

Los webhooks son llamadas HTTP que notifican a tu aplicación cuando ocurren eventos en tu cuenta de Atoship. En lugar de consultar nuestra API una y otra vez para ver novedades, los webhooks envían los datos a tu servidor en tiempo real.

Todos los payloads de webhook siguen un formato uniforme con el tipo de evento, la marca de tiempo y los datos correspondientes.

{
  "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"
    }
  }
}

Cada webhook incluye un encabezado X-Atoship-Signatureque contiene una firma HMAC-SHA256 del payload generada con tu secreto de webhook.

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');
});

Si tu endpoint devuelve un código de estado distinto de 2xx o se agota el tiempo de espera, reintentaremos la entrega del webhook.