Guía de configuración de webhooks

Guía de configuración de webhooks

Configura webhooks para recibir notificaciones instantáneas cuando ocurran eventos de envío en tu cuenta de atoship.

¿Qué son los webhooks?

Definición: Los webhooks son mensajes automáticos que atoship envía a tu servidor cuando ocurren determinados eventos.

Beneficios:

• Notificaciones en tiempo real
• Flujos de trabajo automatizados
• Menos consultas repetitivas (polling)
• Actualizaciones instantáneas

Eventos disponibles

Eventos de envío:

Eventos de pedidos:

Cómo crear un webhook

Paso a paso:

1. Ve a Configuración → Webhooks
2. Haz clic en «Agregar webhook»
3. Ingresa la URL del endpoint
4. Selecciona los eventos que quieres suscribir
5. Guarda la configuración

Requisitos del endpoint

Tu servidor debe:

• Aceptar solicitudes POST
• Usar HTTPS (obligatorio)
• Responder en menos de 30 segundos
• Devolver un código de estado 2xx

Contenido del webhook (payload)

Ejemplo de 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"
  }
}

Verificación de webhooks

Verificación de firma:

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

Verificación en el código:

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;

Política de reintentos

Entregas fallidas:

• Hasta 5 reintentos
• Retroceso exponencial
• 1min → 5min → 30min → 2hr → 24hr

Cómo probar los webhooks

Métodos de prueba:

1. Usa herramientas de prueba de webhooks
2. Envía un evento de prueba desde el panel
3. Revisa los registros de webhooks
4. Confirma que se recibió el payload

Casos de uso comunes

Ejemplos de automatización:

• Actualizar tu sistema de gestión de pedidos
• Enviar notificaciones personalizadas
• Activar actualizaciones de inventario
• Registrar datos de envío
• Alertar ante excepciones

Actualizaciones de seguimiento

Flujo de eventos de seguimiento:

Accepted → In Transit →
Out for Delivery → Delivered

Eventos de excepción:

• Intento de entrega
• Problema con la dirección
• Paquete retenido
• Devuelto al remitente

Configuración con varios endpoints

Configuración avanzada:

• URL distintas por evento
• Endpoints específicos por entorno
• Endpoints de respaldo

Manejo de errores

Buenas prácticas:

1. Registra todos los webhooks recibidos
2. Procésalos de forma asíncrona
3. Devuelve un 200 de inmediato
4. Gestiona los duplicados
5. Verifica las firmas

Registros de webhooks

Ver el historial:

• Todos los webhooks enviados
• Códigos de respuesta
• Intentos de reintento
• Detalles del payload

Consideraciones de seguridad

Protege tu endpoint:

• Verifica siempre las firmas
• Usa solo HTTPS
• Agrega las IP de atoship a la lista de permitidos
• No expongas tus secretos

Lista de IP permitidas

IP de atoship:

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

Solución de problemas

No recibes los webhooks:

1. Verifica la URL del endpoint
2. Revisa el certificado HTTPS
3. Confirma las reglas del firewall
4. Prueba el acceso al endpoint
5. Revisa los registros de webhooks

Eventos duplicados:

• Implementa idempotencia
• Registra los ID de evento
• Omite los eventos ya procesados

Cómo desactivar los webhooks

Para pausar o eliminar:

1. Configuración → Webhooks
2. Selecciona el webhook
3. Desactívalo o elimínalo
4. Confirma la acción

Límites de tasa

Límites de entrega:

• Máximo 1000 eventos por minuto
• Límites por endpoint
• Gestión de picos de tráfico