Webhooks

En vez de consultar en bucle, nos das una URL y Drop te avisa cuando algo cambia. La registrás en la tarjeta «Notificaciones» de Configuraciones → Integraciones, y ahí mismo aparece el signing secret, distinto del secreto de tu credencial, con el que verificás cada entrega.

Qué vas a recibir

Es un único evento a propósito: cubre tanto los cambios que se originan en Drop como los que reporta la paquetería, con el vocabulario de estados de abajo. No hay un evento aparte por guía.

Solo recibís eventos de las órdenes que vos originaste. Las que el dropshipper crea por su cuenta, o las de otro origen, no te generan notificaciones.

Los eventos describen estado, no transición: no traen el estado anterior. Aplicar el mismo evento dos veces te deja igual que aplicarlo una.

Estados de la orden

Esta es la tabla que necesitás para interpretar un webhook. Los mismos valores aparecen en el campo status de las respuestas de GET /orders y en su filtro ?status=, así que sirve para las dos cosas.

Cada orden trae dos campos: status, el identificador estable contra el que tenés que programar, y statusLabel, su traducción al español lista para mostrar. statusLabel puede cambiar de redacción sin aviso; status no.

El ciclo de vida tiene dos tramos. Primero la orden se gestiona dentro de Drop: se valida, se prepara y sale de bodega. A partir de ahí la mueve la paquetería y los cambios los reporta ella. Ambos tramos usan el mismo vocabulario: no tenés que distinguir de dónde viene el cambio.

Tramo 1: la orden dentro de Drop

Tramo 2: el envío en manos de la paquetería

Cómo tratarlos en tu código

Si necesitás agrupar, esta es la clasificación que usamos internamente:

• El avance no es lineal. Un envío puede ir inroute → not_delivered → inroute → delivered. No asumas una secuencia fija ni que un estado no se repite.
• Solo delivered cierra bien el ciclo. returned_to_warehouse, cancelled_in_boxful, cancelled y rejected lo cierran sin entrega; todo lo demás va a seguir cambiando.
• No infieras el cobro del estado del envío, más allá de que delivered significa que se cobró y returned_to_warehouse que no. La liquidación es un proceso aparte.

Tolerá valores que no conozcas. Si la paquetería agrega un estado nuevo, lo vas a recibir tal como nos llega en lugar de perderlo; tu cliente no debería romperse por eso.

Forma de la petición

Drop hace un POST a tu URL con Content-Type: application/json:

POST /tu-endpoint HTTP/1.1
Content-Type: application/json
X-Drop-Event-Id: evt_9f1c2a04-91be-4d33-9d20-2b6e0c7a51ff
X-Drop-Event-Type: order.status_changed
X-Drop-Signature: t=1786462395,v1=4f3c…

{
  "id": "evt_9f1c2a04-91be-4d33-9d20-2b6e0c7a51ff",
  "type": "order.status_changed",
  "createdAt": "2026-08-11T18:22:04.118Z",
  "data": {
    "orderId": "65b000000000000000000301",
    "orderNumber": "1786733712601",
    "sellerId": "65b0000000000000000000f1",
    "status": "inroute",
    "statusLabel": "En ruta a destino",
    "shipmentNumber": "BX-99120",
    "trackingUrl": "https://…/BX-99120",
    "shippingCost": 3.5,
    "codCommissionAmount": 2,
    "codCommissionPercentage": 0.04,
    "estimatedCodCommissionAmount": 2,
    "reasons": [],
    "occurredAt": "2026-08-11T18:22:04.118Z"
  }
}

Las cabeceras que acompañan el POST:

El payload no lleva datos del cliente final: ni nombre, ni teléfono, ni correo, ni dirección. Si los necesitás, pedilos con GET /orders/:id usando tu credencial: así queda registrado quién accedió a esos datos y cuándo.

Motivos de "Verificar"

Cuando status es pending_correction, reasons te dice qué hay que corregir. Te llega tanto si la orden nace en ese estado al crearla como si pasa a él después, porque el proveedor o la bodega la devolvió.

"reasons": [
  {
    "code": "NO_COVERAGE",
    "label": "Sin cobertura",
    "detail": "El courier Forza no tiene cobertura para la ruta de la orden"
  }
]

Puede venir más de un motivo: al crear la orden, por ejemplo, puede faltar la ubicación y además no haber cobertura. Los códigos posibles:

Tratá un code desconocido como un motivo más, no como un error: la lista puede crecer sin cambiar de versión. En ese caso mostrá label.

Motivos de una novedad

Cuando status es issue, reasons te dice qué reportó la paquetería, con la misma forma que los motivos de "Verificar". detail trae el comentario del repartidor, que es lo que conviene contarle al cliente final.

"reasons": [
  {
    "code": "COURIER_MANAGEMENT",
    "label": "Gestión del courier",
    "detail": "No se encuentra ella en el lugar"
  }
]

Los códigos que vas a ver con más frecuencia:

Igual que en "Verificar", tratá un code desconocido como un motivo más y mostrá label.

Dos cosas a tener en cuenta:

• Llega con unos segundos de atraso. La paquetería registra el detalle después del cambio de estado, así que el evento issue sale entre 30 segundos y un minuto y medio después. Si mientras tanto la orden cambió de estado, ese evento te llega antes: ordená por occurredAt.
• Siempre trae al menos un motivo. Si la paquetería no registra el detalle en ese tiempo, el evento issue no se envía. Vas a recibir el siguiente cambio de estado de la orden, y siempre podés consultarla con GET /orders/:id.

El evento de prueba

En la tarjeta «Notificaciones», una vez guardada tu URL, aparece el botón «Enviar evento de prueba»: sirve para comprobar que tu endpoint responde antes de que pase nada real. Llega por el mismo camino que uno de verdad, misma firma, mismas cabeceras y el mismo sobre, así que podés validarlo con tu código de producción. Lo que lo distingue es la clave test:

{
  "id": "evt_test_9f1c2a04-91be-4d33-9d20-2b6e0c7a51ff",
  "type": "order.status_changed",
  "createdAt": "2026-08-19T18:22:04.118Z",
  "test": true,
  "data": {
    "orderId": "000000000000000000000000",
    "orderNumber": "TEST-0001",
    "status": "registered",
    "shipmentNumber": null,
    "trackingUrl": null,
    "shippingCost": null,
    "codCommissionAmount": null,
    "codCommissionPercentage": null,
    "estimatedCodCommissionAmount": null,
    "reasons": []
  }
}

if (event.test) return res.sendStatus(200);

Verificá la firma antes de procesar

Sin esto, cualquiera que conozca tu URL puede inventarte órdenes.

X-Drop-Signature tiene la forma t=<timestamp>,v1=<hmac>, donde el HMAC es:

HMAC_SHA256( tu_signing_secret, "<timestamp>.<cuerpo crudo>" )

En hex minúscula. El cuerpo es el que llegó, byte a byte: no lo re-serialices antes de verificar.

const crypto = require('crypto');

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map(kv => kv.split('=')));

  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
  if (age > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  // Comparación en tiempo constante.
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? '');

  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

El timestamp va dentro del HMAC para que una entrega capturada no se pueda reenviar indefinidamente: rechazá las que estén fuera de tu ventana.

Entrega y reintentos

La entrega es at-least-once: podés recibir el mismo evento más de una vez. X-Drop-Event-Id es tu llave de deduplicación: es estable entre reintentos, guardalo y descartá los repetidos.

Contamos como éxito cualquier respuesta 2xx. Todo lo demás, incluidos 3xx, timeouts y errores de conexión, es un fallo y se reintenta.

Respondé rápido: el timeout es de 10 segundos. Si tu procesamiento es lento, encolá el evento y respondé 200 de inmediato.

Son 6 intentos por defecto. Agotados, la entrega queda marcada como fallida y no se vuelve a intentar.

Tu suscripción puede desactivarse sola tras 20 fallas consecutivas, para no insistir contra un endpoint muerto. Reactivarla es manual: escribinos. Una entrega exitosa reinicia el contador.

Reconciliación

Los webhooks se pueden perder: tu endpoint estuvo caído más allá de los reintentos, o la suscripción se desactivó. La contraparte es consultar por fecha de modificación:

GET /integrations/v1/orders?updatedSince=2026-08-11T00:00:00.000Z

Devuelve solo tus órdenes, paginadas. Corriéndolo periódicamente cerrás cualquier hueco. No lo trates como opcional: es lo que hace que tu sistema converja aunque una entrega se pierda.

Referencia: GET /orders.

Recomendaciones

• Respondé 200 antes de procesar. Encolá y procesá aparte.
• Deduplicá por X-Drop-Event-Id, no por el contenido.
• No asumas orden de llegada. Un reintento puede llegar después de un evento más nuevo; usá occurredAt para descartar los atrasados.
• Tolerá campos nuevos. Agregarlos al payload no es un cambio incompatible.
• Guardá el signing secret como una credencial, no en el repositorio.