Tipos de eventos de webhook
Los webhooks te permiten recibir notificaciones en tiempo real cuando ocurren eventos en tu cuenta de atoship. Configura endpoints de webhook para escuchar los tipos de evento que te interesen.
Verificación de firma
Todas las solicitudes de webhook incluyen un encabezado de firma para su verificación. Verifica la firma calculando el HMAC-SHA256 del cuerpo sin procesar de la solicitud con tu clave secreta de webhook.
X-Atoship-Signature: sha256=abc123...Eventos disponibles
Eventos de etiqueta
Eventos relacionados con el ciclo de vida de la etiqueta de envío
label.createdSe activa cuando se compra correctamente una nueva etiqueta de envío
label.voidedSe activa cuando una etiqueta de envío se anula o cancela
label.refundedSe activa cuando se procesa el reembolso de una etiqueta
Eventos de rastreo
Eventos relacionados con las actualizaciones de rastreo del paquete
tracking.updatedSe activa cuando cambia el estado de rastreo de un envío
tracking.deliveredSe activa cuando un paquete se entrega correctamente
tracking.exceptionSe activa cuando ocurre una incidencia de entrega
tracking.return_to_senderSe activa cuando un paquete se devuelve al remitente
Eventos de seguro
Eventos relacionados con el seguro de envío
insurance.purchasedSe activa cuando se contrata un seguro para un envío
insurance.claim.filedSe activa cuando se presenta una reclamación de seguro
insurance.claim.approvedSe activa cuando se aprueba una reclamación de seguro
insurance.claim.deniedSe activa cuando se rechaza una reclamación de seguro
Eventos de devolución
Eventos relacionados con los envíos de devolución
return.createdSe activa cuando se crea una etiqueta de devolución
return.in_transitSe activa cuando un paquete de devolución está en tránsito
return.receivedSe activa cuando se recibe un paquete de devolución
Eventos de cuenta
Eventos relacionados con la cuenta y la facturación
account.balance.lowSe activa cuando el saldo de la cuenta baja del umbral
account.balance.depletedSe activa cuando el saldo de la cuenta llega a cero
Buenas prácticas
Devuelve un estado 200 en menos de 30 segundos para confirmar la recepción
Usa el ID del evento para eliminar eventos duplicados
Valida siempre la firma del webhook antes de procesarlo
Los webhooks fallidos se reintentan hasta 5 veces con retroceso exponencial
| 1 | { |
| 2 | "id": "evt_1234567890", |
| 3 | "object": "Event", |
| 4 | "type": "label.created", |
| 5 | "created_at": "2025-01-14T10: 00: 00Z", |
| 6 | "data": { |
| 7 | "id": "lbl_k7x9m2p4q8r5", |
| 8 | "object": "Label", |
| 9 | "status": "purchased", |
| 10 | "tracking_number": "9400111899223456789012", |
| 11 | "carrier": "USPS", |
| 12 | "service": "Priority Mail", |
| 13 | "rate": 8.95, |
| 14 | "currency": "USD" |
| 15 | } |
| 16 | } |