DOCS
InicioPara proveedores logísticos Webhooks

Escuche eventos con webhooks

Reciba notificaciones de eventos en tiempo real para su integración con Zonos.

Los webhooks ofrecen una forma de que Zonos notifique de forma proactiva a sus sistemas externos cada vez que ocurren determinados eventos. Cuando se produce el evento suscrito, Zonos enviará una solicitud HTTP POST a la URL del webhook que usted especifique. El cuerpo de la solicitud contendrá los detalles del evento, lo que permitirá a su sistema gestionarlo de forma programática.

Los webhooks son útiles para integrar Zonos con otras plataformas, activar flujos de trabajo automatizados y mantener los datos sincronizados entre sistemas en tiempo real. Por ejemplo, podría usar webhooks para:

  • Actualizar su sistema de gestión de pedidos cuando se crea un pedido en Zonos
  • Notificar a su proveedor de cumplimiento cuando se cancela un envío
  • Registrar cambios de estado de pedidos internacionales con fines de auditoría

Tipos de webhook 

Todos los tipos de webhook disponibles se incluyen en el enum WebhookType. Los payloads de ejemplo de cada uno se encuentran en nuestra guía de Tipos de eventos.

Creación de webhooks 

Para crear un webhook mediante la API:

1mutation WebhookCreate($input: WebhookCreateInput!) {
2 webhookCreate(input: $input) {
3 id
4 url
5 type
6 status
7 secret
8 headers {
9 key
10 }
11 }
12}

Importante: Guarde el valor de secret al crear el webhook. Solo se devuelve en este momento y lo necesitará para verificar las firmas de los webhooks. Consulte Verificación de las firmas de los webhooks más abajo.

Edición de detalles del webhook 

Para editar un webhook existente mediante la API:

1mutation WebhookUpdate($input: WebhookUpdateInput!) {
2 webhookUpdate(input: $input) {
3 id
4 url
5 type
6 status
7 }
8}

Verificación de las firmas de los webhooks 

Cada solicitud de webhook que envía Zonos incluye un encabezado zonos-signature para que pueda confirmar que la solicitud proviene realmente de Zonos y que el payload no se alteró durante el tránsito.

El valor del encabezado tiene el siguiente formato:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — la hora, en milisegundos de época Unix, en que se firmó la solicitud.
  • hmac — una firma HMAC-SHA256 del cuerpo de la solicitud JSON sin procesar, calculada usando el secreto de su webhook como clave y codificada en Base64.

Para verificar una solicitud:

  1. Extraiga los valores timestamp y hmac del encabezado zonos-signature.
  2. Calcule su propia firma HMAC-SHA256 sobre el cuerpo de la solicitud sin procesar y sin analizar, usando el secreto que recibió al crear el webhook.
  3. Compare su firma calculada con el valor hmac mediante una comparación de tiempo constante y rechace la solicitud si no coinciden.
  4. Opcionalmente, rechace las solicitudes en las que timestamp sea anterior a unos minutos, para protegerse contra la reproducción de una solicitud capturada. Zonos no impone por sí mismo una ventana de entrega, por lo que esta verificación queda a su criterio.
1const crypto = require("crypto");
2 
3function verifyZonosWebhook(rawBody, signatureHeader, secret) {
4 const [timestampPart, hmacPart] = signatureHeader.split(",");
5 const receivedHmac = hmacPart.split("=")[1];
6 
7 const expectedHmac = crypto
8 .createHmac("sha256", secret)
9 .update(rawBody)
10 .digest("base64");
11 
12 const receivedBuffer = Buffer.from(receivedHmac);
13 const expectedBuffer = Buffer.from(expectedHmac);
14 
15 if (receivedBuffer.length !== expectedBuffer.length) {
16 return false;
17 }
18 
19 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
20}

Nota: Si configuró encabezados personalizados en su webhook, estos también se incluyen textualmente en cada solicitud junto con zonos-signature.

Visualización de registros de webhook 

Para ver los registros de webhook mediante la API:

1query WebhookLogs(
2$first: Int
3$after: String
4$filter: WebhookLogsFilterInput
5) {
6 webhookLogs(first: $first, after: $after, filter: $filter) {
7 edges {
8 node {
9 id
10 type
11 url
12 createdAt
13 responseStatus
14 }
15 }
16 }
17}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

WebhookCreateInput WebhookLogsFilterInput WebhookUpdateInput

MUTATIONS

webhookCreate webhookUpdate

¿Fue útil esta página?

Obtener soporte·Documentos legales·© 2026 Zonos
En esta página:
  • Escuche eventos con webhooks
  • Tipos de webhook
  • Creación de webhooks
  • Edición de detalles del webhook
  • Verificación de las firmas de los webhooks
  • Visualización de registros de webhook