Webhooks públicos: envía eventos de pedidos, envíos y facturas a tu propio sistema

Suscríbete a los eventos de Docklify —pedido creado, pedido cumplido, envío entregado al transportista, factura emitida, entrega completada— y recíbelos como envíos HTTPS firmados en tu propio endpoint, con eventos de prueba, reintentos automáticos y registro de entregas.

Los webhooks públicos convierten lo que pasa en Docklify en mensajes para tu propio sistema. En cuanto se crea un pedido, se entrega un envío al transportista o se emite una factura, Docklify envía un post HTTPS a una dirección que tú controlas. Usos típicos: sincronizar pedidos con tu ERP o tu contabilidad, avisar a tus clientes con tus propias palabras, alimentar tus paneles o arrancar un proceso posterior sin consultar una API.

Eventos a los que puedes suscribirte#

• order.created: se crea un pedido de venta (manual, portal del cliente o conversión de CRM).
• order.allocated: un pedido queda asignado y el inventario reservado.
• order.fulfilled: un pedido queda totalmente cumplido; incluye número de rastreo y transportista.
• order.cancelled: un pedido se cancela; incluye el código de motivo.
• order.delivered: un pedido se marca como entregado.
• shipment.fulfilled: un envío de WMS se entrega al transportista; incluye el número de rastreo.
• receipt.completed: una recepción de entrada se completa, con todas las líneas recibidas.
• inventory.adjusted: el inventario se ajusta directamente en una ubicación.
• invoice.issued: se genera una factura por cobrar. Las nuevas nacen en borrador; el campo de estado muestra el estado actual.
• delivery.completed: una entrega de última milla se firma y se completa, con la prueba de entrega capturada.
• test.ping: el evento de prueba. Envíalo cuando quieras para comprobar que tu endpoint responde y que la verificación de firma funciona.

Crear una suscripción#

1. Abre Integration → Webhooks y haz clic en Nueva suscripción.
2. Nombre: ponle un nombre que tu equipo reconozca, por ejemplo «Sincronización ERP».
3. URL: la dirección https de tu servidor que recibirá los eventos. Debe usar https y resolverse a una dirección pública: las direcciones privadas, de red local o de bucle se rechazan.
4. Eventos: marca los eventos que quieres. Puedes cambiar la selección cuando quieras.
5. Guarda y copia el secreto de firma: empieza con whsec_. Guárdalo en la configuración de tu servidor; lo necesitas para verificar que las entregas vienen realmente de Docklify. Puedes volver a verlo, o rotarlo, en la página de Webhooks cuando quieras.

Qué debe hacer tu receptor#

Cada entrega es un post HTTPS con un cuerpo JSON: el sobre. El sobre dice qué pasó (type), cuándo (created_at) y lleva los detalles en data:

{
  "id": "<event id>",
  "type": "order.fulfilled",
  "created_at": "2026-10-20T12:00:00.000Z",
  "organization_id": "<your organization id>",
  "data": {
    "order_id": "<order id>",
    "order_no": "SO-1001",
    "status": "fulfilled",
    "tracking_number": "<tracking number>",
    "carrier_code": "ups"
  }
}

• Deduplica por id: la entrega es «al menos una vez». Los reintentos y los reenvíos manuales reutilizan el mismo id de evento: guarda los id procesados y salta los repetidos.
• Responde 2xx, y responde rápido: cualquier 2xx cuenta como éxito. Las entregas caducan a los 10 segundos; si tu proceso es lento, guarda primero el evento, responde 200 y luego procésalo.
• Todo lo demás cuenta como fallo: un estado no 2xx, una redirección (el 3xx no se sigue), un tiempo de espera agotado o una dirección inalcanzable; todo dispara los reintentos automáticos descritos abajo.

Verificar la firma#

Cualquiera que conozca tu URL podría enviarte eventos falsos, por eso cada entrega va firmada: verifica la firma antes de confiar en los datos. La especificación completa (nombres de encabezado, el algoritmo exacto y ejemplos de una línea en Node y Python) está en la documentación de la API, en la sección Webhooks. Los puntos clave:

• Cada entrega lleva el encabezado X-Docklify-Signature, con la forma t=<segundos unix>,v1=<hex>. La misma entrega lleva también X-Docklify-Event (el tipo de evento) y X-Docklify-Delivery (el id de entrega).
• v1 es el HMAC-SHA256 en hex de la cadena «<t>.<cuerpo original>», con tu secreto de firma como clave.
• Calcula siempre sobre el cuerpo original de la petición, tal como llegó. Nunca analices el JSON y lo vuelvas a serializar: cambian los espacios y el orden de las claves, y la firma no coincidirá.
• Si la firma no coincide, no proceses el evento.

Enviar un evento de prueba#

1. En Integration → Webhooks, abre tu suscripción y elige Enviar evento de prueba.
2. Docklify entrega al instante un test.ping a tu URL. Los eventos de prueba pueden enviarse a cualquier suscripción, aunque test.ping nunca esté en su lista de eventos.
3. Revisa el registro de entregas: una fila en estado entregado, más la firma verificada en tu servidor, significa que estás listo para los eventos reales.

Registro de entregas y solución de problemas#

Cada entrega queda registrada en el registro de entregas (Integration → Webhooks → Entregas): el tipo de evento, el estado (pendiente, entregado o fallido), cuántos intentos se hicieron, el último código HTTP y error, y la hora del siguiente reintento. Una entrega fallida se reintenta automáticamente tras 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas: seis intentos en total. Tras el último queda como fallida hasta que la reenvíes manualmente desde el registro; el reenvío reutiliza el mismo id de evento, así que tu deduplicación lo mantiene seguro.

• Dirección inalcanzable: tu servidor está caído, la URL está mal o el nombre no se resuelve a una dirección pública. Arregla el endpoint y reenvía desde el registro.
• Problemas de certificado: un certificado TLS caducado o autofirmado hace fallar la entrega. Usa un certificado válido de una autoridad pública.
• Respuesta no 2xx: tu receptor falló o rechazó el evento. Lee el código y el error en el registro, corrige la causa y reenvía.
• Tiempo agotado: tu receptor tardó más de 10 segundos. Responde 2xx primero y haz el trabajo pesado en segundo plano.
• La firma no coincide en tu lado: suele ser un cuerpo reserializado, o un secreto antiguo aún en uso tras una rotación; ver Verificar la firma arriba.

Pausar una suscripción y rotar el secreto#

• Pausar: pon la suscripción en Pausada en la página de Webhooks. Mientras esté pausada, Docklify no le entrega eventos nuevos. Reanúdala cuando quieras: pausar es la forma segura de sacar un endpoint de servicio por mantenimiento.
• Rotar el secreto: si un secreto pudo filtrarse, o se fue un compañero que lo conocía, rótalo en la página de la suscripción. Tras la rotación, las entregas se firman solo con el secreto nuevo, así que actualiza tu servidor al mismo tiempo: un receptor con el secreto antiguo rechazará las entregas nuevas.