WEBHOOKS
Ganchos web
Reciba eventos en tiempo real de Superroute — pedidos, cambios de estado, actualizaciones de seguimiento. Con cargas firmadas, reintentos automáticos y depurador integrado.
WEBHOOKS
Reciba eventos en tiempo real de Superroute — pedidos, cambios de estado, actualizaciones de seguimiento. Con cargas firmadas, reintentos automáticos y depurador integrado.
Un webhook es una solicitud HTTP POST que Superroute envía a una URL configurada por usted cada vez que ocurre algo — se crea un pedido, se completa una entrega, se registra un evento de seguimiento. Usted construye un endpoint receptor; nosotros le entregamos el evento.
Los eventos se ponen en cola y se envían de forma asíncrona. Cada solicitud lleva una firma HMAC-SHA256 para que pueda verificar su origen. Las entregas fallidas (no 2xx o tiempo de espera) se reintentan con retroceso exponencial hasta 5 veces.
Usted configura un secreto compartido en la página de ajustes. Cada webhook saliente se firma con ese secreto. Su receptor recalcula la firma y la compara — si coinciden, la carga es genuina y no ha sido alterada.
Hay ocho tipos de eventos salientes disponibles. Cada uno tiene su propio campo URL en la página de ajustes — puede suscribirse a cualquier subconjunto.
Descripción legible por máquina de todos los eventos salientes, con esquemas de carga útil, encabezados y calendarios de reintento (AsyncAPI 3.0): asyncapi-webhooks.json
Se dispara cuando se crea un pedido de entrega local (Delivery / Pickup / P2P) por cualquier vía: formulario web, API REST/GraphQL, sincronización con plataforma de e-commerce, reglas automáticas, filas importadas, etc. Excluye los pedidos label-service y otros tipos que no son de entrega. Se omite en el flujo por lotes cuando el mismo destinatario tiene también order_create_async_postback_url configurado. Configure con order_create_webhook_url.
Ejemplos de CargaSe dispara en cada transición de estado del pedido — recogido, en tránsito, entregado, excepción, cancelado. Configure con order_status_change_webhook_url.
Ejemplos de CargaSe dispara en cada evento del ciclo de vida del seguimiento de un paquete (información enviada, inicio de entrega, entrega exitosa, no entregado, etc.). Configure con tracking_event_webhook_url. Los eventos de entrega y de recogida también incluyen la prueba de entrega: proof_files y proof_files_detail (file_id, type, url, full_url, URL de descarga firmada). Las fotos subidas después del evento llegan como pod.files_updated. Cada archivo incluye además el contexto de su evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) y service_status (1 = success / 2 = failed); en archivos antiguos sin evento registrado son null.
Ejemplos de CargaSe dispara una vez tras finalizar una importación masiva de pedidos. La carga contiene el array de resultados por fila. Configure con order_create_async_postback_url.
Ejemplos de CargaSe dispara cuando una foto de entrega o firma se añade, se reemplaza o se elimina (action: added / updated / removed) — un envío por archivo, sin más sondeo de adjuntos. Se activa configurando pod_files_webhook_url. Cada archivo incluye además el contexto de su evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) y service_status (1 = success / 2 = failed); en archivos antiguos sin evento registrado son null. Cuando el personal reemplaza una foto o firma, o establece una versión archivada como actual, el archivo se envía con action: updated y contiene solo la imagen actual; las versiones archivadas nunca se envían.
Ejemplos de CargaSe dispara cuando un pedido se elimina permanentemente, para que su sistema pueda reflejar la eliminación. Se activa configurando order_deleted_webhook_url.
Ejemplos de CargaSe dispara cuando un intento de cancelación es rechazado (por ejemplo, el pedido ya está en reparto), para que su equipo de operaciones pueda supervisar las cancelaciones fallidas sin consultar la API. Se activa configurando order_cancel_failed_webhook_url.
Ejemplos de CargaSe dispara cuando un asiento del tablero de rutas cambia de manos o el tablero cambia de estado — el campo action indica qué ocurrió (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Solo a nivel de empresa. Suscripción mediante route_board_webhook_url.
Ejemplos de CargaUn canal de webhooks independiente para proveedors de entrega externos integrados con taquillas inteligentes. Los eventos se entregan al endpoint configurado para su cuenta de proveedor, y cada endpoint puede suscribirse a cualquier subconjunto de tipos de evento.
Puertas Abiertas — Se dispara en el momento en que se abren las puertas de los casilleros para un intento de entrega — tanto si el repartidor usó la pantalla del casillero con el código de acceso como la API de apertura remota — incluidas las reaperturas por reasignación. El bloque opening lista cada compartimento abierto con su grid_id, el número de puerta de hardware compartment_number y el pickup_locker_number (número secuencial de visualización contado de arriba abajo por columna y luego de izquierda a derecha). Cada compartimento incluye además pickup_locker_code: la etiqueta "{shelf_code}-{pickup_locker_number}" a la que se envía al destinatario; null cuando el compartimento no tiene número de recogida. La carga útil también incluye pickup_code: el código de recogida del destinatario, asignado en el momento en que se abren las puertas; sigue siendo el mismo código después de que el repartidor confirme el depósito, y solo puede usarse para recoger una vez confirmado el depósito.
Ejemplos de CargaEntregado en la taquilla — Se dispara cuando se confirma un depósito y los paquetes están en la taquilla. La carga incluye el código de recogida del destinatario. Cada compartimento incluye además pickup_locker_code: la etiqueta "{shelf_code}-{pickup_locker_number}" a la que se envía al destinatario; null cuando el compartimento no tiene número de recogida. Para puertas abiertas mediante la API de apertura remota, la plataforma liquida el depósito en cuanto la taquilla informa de que todas las puertas abiertas están cerradas, por lo que este evento se dispara sin llamada a confirm; confirmed_by indica la vía de liquidación: courier_terminal, partner_api, door_close, timeout_door_closed o console.
Ejemplos de CargaRecogido — Se dispara cuando el destinatario ha recogido los paquetes depositados.
Ejemplos de CargaEntrega fallida — Se dispara cuando una entrega falla; se incluyen los códigos de fallo por paquete.
Ejemplos de CargaCaducado — Se dispara cuando un código de entrega sin usar o un depósito sin recoger supera su fecha de caducidad.
Ejemplos de CargaCancelado — Se dispara cuando una entrega se cancela antes de completarse.
Ejemplos de CargaReapertura de corrección — Se dispara cuando los compartimentos ocupados se reabren dentro de la ventana de corrección para corregir una colocación errónea — desde la pantalla de la taquilla o mediante la API. El bloque correction enumera los compartimentos reabiertos. Cada compartimento incluye además pickup_locker_code: la etiqueta "{shelf_code}-{pickup_locker_number}" a la que se envía al destinatario; null cuando el compartimento no tiene número de recogida.
Ejemplos de CargaCódigo de recogida cambiado — Se dispara cuando el socio renueva el código de entrega o el código de recogida de una entrega. El bloque rotation indica qué código se sustituyó, cuándo y si se reenvió la notificación al destinatario; el código nuevo nunca viaja en un webhook, solo se revela en la respuesta directa de la API de renovación.
Ejemplos de CargaPaquete de transportista distribuido — Se dispara cuando un paquete preavisado del transportista recibido en un almacén se coloca en una orden de distribución hacia el lugar indicado por el transportista. El bloque data lleva el número de paquete, la referencia del transportista y el número de socio, la orden de distribución (order_id, order_ref, status) y los lugares de origen y destino. Solo se registra para transportistas con cuenta de proveedor.
Ejemplos de CargaPaquete de transportista cargado — Se dispara cuando el paquete se escanea en el camión en el almacén de origen; distribution.status es in_transit y loaded_at está fijado.
Ejemplos de CargaPaquete de transportista entregado en el destino — Se dispara cuando el conductor entrega la orden de distribución en el lugar; distribution.status es delivered y delivered_at está fijado. La colocación es un evento posterior e independiente.
Ejemplos de CargaPaquete de transportista colocado en el destino — Se dispara cuando el paquete se coloca en el lugar, en un compartimento de taquilla o en una estantería; location lleva grid_id, grid_code y shelf_code. La notificación de recogida al destinatario sale en ese momento.
Ejemplos de CargaPaquete de transportista retirado de la distribución — Se dispara cuando el paquete se retira de una orden de distribución antes de salir, o la orden se cancela; distribution.reason es removed o cancelled. El paquete vuelve a la lista de distribución del almacén.
Ejemplos de CargaFirma y Verificación: Los webhooks de taquillas de proveedors usan su propio esquema de firma: X-Webhook-Signature es base64(HMAC-SHA256(secreto, marca de tiempo + "\n" + id de entrega + "\n" + cuerpo sin procesar)), donde la marca de tiempo y el id de entrega provienen de las cabeceras X-Webhook-Timestamp y X-Webhook-Delivery-Id. Verifique también X-Webhook-Content-Digest (SHA-256 del cuerpo) y rechace marcas de tiempo obsoletas. X-Webhook-Id se mantiene estable entre reintentos — úselo para la idempotencia.
Cómo Configurar: Los endpoints se gestionan en Entrega de terceros → Taquilla de proveedors → Configuración, un endpoint por proveedor, con una lista de eventos seleccionable. Las entregas fallidas se reintentan con retroceso exponencial hasta 7 veces antes de pasar a la lista de fallidos; los eventos fallidos pueden reenviarse manualmente desde la página de eventos.
Eventos de sandbox (taquillas simuladas): Las entregas creadas contra taquillas simuladas emiten los mismos eventos de webhook que producción, firmados con el mismo secreto, para que pueda desarrollar con tráfico realista. Los eventos de sandbox se marcan de tres formas: la carga incluye "livemode": false, el event_id empieza por PLE-MOCK- y la solicitud lleva la cabecera X-Webhook-Test: 1. Si el endpoint tiene configurada una URL de sandbox, los eventos de sandbox se envían allí en lugar de a la URL de producción; en caso contrario recurren a la URL de producción, siempre marcados. El interruptor «Entregar eventos de sandbox» detiene por completo la entrega de sandbox.
Webhooks de entrega de paquetes enviados a los proveedores de entrega externos (mensajerías). Cubren el ciclo de vida de las asignaciones de entrega, de modo que la mensajería ya no necesita sondear en busca de nuevos trabajos. Esta categoría es independiente de los eventos de taquilla inteligente de más abajo: cada proveedor configura por categoría un endpoint, un secreto de firma y una suscripción de eventos independientes — en su propio portal de proveedor o a través del operador de la plataforma.
Asignación creada — Se dispara cuando un pedido se asigna al proveedor — por una regla automática o manualmente. La carga útil incluye el número de asignación, los identificadores del pedido y los números de seguimiento de los paquetes.
Ejemplos de CargaPaquetes entregados en mano — Se dispara cuando el almacén ha entregado físicamente al proveedor todos los paquetes de la asignación.
Ejemplos de CargaAsignación cancelada — Se dispara cuando la plataforma retira una asignación al proveedor. El campo reason distingue entre cancelled (la asignación se canceló en el transportista), fallback_to_self_delivery (la plataforma recuperó el pedido para entregarlo por sus propios medios) y reassigned (el pedido se trasladó a otro proveedor).
Ejemplos de CargaEntrega parcial — Se activa cuando parte de un envío ha sido entregada mientras otros paquetes siguen en curso. El array packages incluye el resultado de cada bulto y legs enumera los pedidos externos registrados con el transportista: uno por paquete cuando el transportista no admite envíos de varios bultos.
Ejemplos de CargaFirma y Verificación: Los webhooks de entrega de terceros usan el mismo esquema de firma que los webhooks de taquillas de proveedors: X-Webhook-Signature es base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), donde el timestamp y el delivery id se toman de las cabeceras X-Webhook-Timestamp y X-Webhook-Delivery-Id. Verifique también X-Webhook-Content-Digest (SHA-256 del cuerpo) y rechace marcas de tiempo obsoletas. X-Webhook-Id se mantiene estable entre reintentos — úselo para la idempotencia.
Cómo Configurar: Los proveedores configuran este endpoint por sí mismos en el portal del proveedor (Configuración de Webhooks), o lo hace el operador de la plataforma en Entrega de terceros → Proveedores → Webhooks. Un endpoint por proveedor con una lista de eventos seleccionable. El secreto de firma puede generarse automáticamente o establecerse con un valor personalizado, y puede consultarse en la página de configuración. Las entregas fallidas se reintentan con retroceso exponencial hasta 7 veces antes de pasar a la lista de fallidos; los eventos fallidos pueden reenviarse manualmente. Desde la página de configuración se puede enviar en cualquier momento un evento de prueba (mock) firmado: las solicitudes de prueba llevan la cabecera X-Webhook-Test: 1 y "test": true dentro de los datos del payload.
Pushes firmados sobre entregas intercambiadas por el Open Order Handoff Protocol: cambios de ciclo de vida (aceptada, rechazada, expirada, cancelada), respuestas a enmiendas, eventos de seguimiento y nuevas líneas de liquidación. Suscrito por token OHP mediante POST /api/v1/ohp/subscriptions; el endpoint debe devolver un desafío antes de que exista la suscripción. Cada carga es el sobre OHP; message_id se mantiene igual en cada reintento — deduplique por él. El pull sigue siendo la fuente de verdad.
Firma y Verificación: X-Ohp-Signature: v1= + HMAC-SHA256 hexadecimal de "{timestamp}.{raw body}" con el secreto de la suscripción. X-Ohp-Timestamp cambia por intento; X-Ohp-Delivery es igual a message_id. CloudEvents y Standard Webhooks están disponibles por suscripción.
Cómo Configurar: Gestionado con el token OHP: POST /api/v1/ohp/subscriptions (url, secret, events, format, signature), GET para listar, DELETE para revocar. El catálogo legible por máquina lista cada evento bajo el remitente ohp.
Eventos detallados y opcionales junto al webhook clásico order.status_change (que no cambia): a quién se asignó, si el conductor aceptó, cuándo se recogió el paquete, cuándo está en camino, entregado o fallido, además de los cambios de turno de los conductores y sus posiciones limitadas por frecuencia. No se envía nada hasta que configure las URL siguientes.
Se asignó un conductor al pedido (manualmente, por planificación de rutas o por asignación automática). data.source = auto_assign cuando lo hizo el orquestador.
Ejemplos de CargaEl pedido perdió a su conductor (traspaso, revocación, rechazo, tiempo agotado). data.previous_driver_id indica quién lo tenía.
Ejemplos de CargaEl conductor aceptó en la app un pedido asignado automáticamente (turno de conductores con aceptación obligatoria).
Ejemplos de CargaEl conductor rechazó un pedido asignado; data.reason lleva el motivo opcional en texto libre.
Ejemplos de CargaEl conductor inició la recogida (estado Recogida iniciada / Fuera para recoger).
Ejemplos de CargaEl paquete fue recogido (estado Ya recogido).
Ejemplos de CargaEl paquete va de camino al destinatario (estado Entrega iniciada / Fuera para entrega).
Ejemplos de CargaLa entrega se completó con éxito (estado Exitoso).
Ejemplos de CargaEl intento de entrega falló (Reentregar más tarde, Necesita reprogramación, Rechazado por el destinatario).
Ejemplos de CargaEl pedido fue cancelado.
Ejemplos de CargaEl personal (o un conductor, cuando se permite) marcó el pedido como listo para recoger (Opciones de despacho → listo para recoger).
Ejemplos de CargaUn conductor entró o salió de turno en la app (opción de turno de conductores).
Ejemplos de CargaUna posición del conductor procedente de la app o del rastreador, limitada por conductor mediante driver_location_min_interval_sec (60 s por defecto). Se envía solo a driver_location_webhook_url.
Ejemplos de CargaCómo Configurar: Ajustes → Webhooks (o GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url recibe todos los eventos order.* y driver.on_duty_changed; order_lifecycle_events los limita a una lista separada por comas; driver_location_webhook_url y driver_location_min_interval_sec controlan driver.location_update. Se pueden indicar varias URL separadas por comas. Las entregas aparecen en el registro de entregas de webhooks con reference_type order / driver.
Firma y Verificación: Firmado exactamente igual que cualquier otro webhook saliente de su cuenta: cabecera Signature heredada más X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 con su webhook_sign_secret. Los reintentos reutilizan el mismo event_id: deduplique a partir de él.
Eventos opcionales para los paquetes que gestionan sus taquillas inteligentes, quioscos y buzones inteligentes: un paquete depositado en una máquina, retirado, sacado por el personal o que ha superado su plazo de retirada, y las incidencias abiertas o resueltas sobre él. Solo aditivo: ningún webhook existente cambia y no se envía nada hasta que configure device_order_webhook_url.
Se depositó un paquete en la máquina y espera a la siguiente persona (destinatario, mensajero u operador, véase data.device_order.next_actor). due_at es la fecha límite de retirada.
Ejemplos de CargaLa persona a la que esperaba retiró el paquete: el destinatario, el mensajero o el personal que vacía un buzón inteligente.
Ejemplos de CargaEl personal sacó el paquete de la máquina. removal_reason indica el motivo: overdue_return, handover, relay, anomaly o recovery.
Ejemplos de CargaEl paquete superó su due_at sin ser retirado. Sigue en la máquina y su código sigue funcionando; se establece overdue_at y next_actor pasa a operator.
Ejemplos de CargaSe abrió una incidencia sobre la gestión (por ejemplo door_left_open, deposit_unverified, item_missing, overdue). data.exception incluye id, type, severity y status.
Ejemplos de CargaUna persona cerró una incidencia sobre la gestión. data.exception.status es resolved o dismissed y resolution_action indica lo que se hizo.
Ejemplos de CargaEjemplos de Carga: data.device_order: id, kind, status, next_actor, device_type, device_id, device_name, grid_code, reference_number, order_id, external_order_id, due_at, overdue_at, stored_at, ended_at, removal_reason (horas en ISO 8601, null mientras no se alcancen). Los eventos de incidencia añaden data.exception: id, type, severity, status, resolution_action. El código de retirada nunca se incluye. event_id es DOE-<id del evento del registro> y no cambia en los reintentos.
Cómo Configurar: Ajustes → Webhooks (o GET/PUT /api/v1/webhook-settings): device_order_webhook_url recibe todos los eventos device_order.*; device_order_events lo limita a una lista separada por comas. Se pueden indicar varias URL separadas por comas. Las entregas aparecen en el registro de entregas de webhooks con reference_type device_order.
Firma y Verificación: Firmado exactamente igual que cualquier otro webhook saliente de su cuenta: cabecera Signature heredada más X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 con su webhook_sign_secret. Los reintentos reutilizan el mismo event_id: deduplique a partir de él.
Los paquetes que un transportista asociado entrega en sus taquillas con su propia cuenta no se envían por este canal; el socio los recibe a través de sus webhooks de taquillas del proveedor.
Puede configurar webhooks en dos niveles: a nivel de negocio (cubre todo) o por cliente (anula para esa subcuenta B2B específica).
Inicie sesión y vaya a Ajustes → API y Webhooks. Las anulaciones por cliente están en la página de detalle del cliente.
Elija cualquier cadena de al menos 16 caracteres, idealmente 32+ bytes aleatorios. Su receptor lo usará para verificar firmas.
Rellene solo las URLs de los eventos que le interesan. Deje el resto en blanco para omitirlos.
webhook_sign_secretUsted configura un secreto compartido en la página de ajustes. Cada webhook saliente se firma con ese secreto. Su receptor recalcula la firma y la compara — si coinciden, la carga es genuina y no ha sido alterada.order_create_webhook_urlSe dispara cuando se crea un pedido de entrega local (Delivery / Pickup / P2P) por cualquier vía: formulario web, API REST/GraphQL, sincronización con plataforma de e-commerce, reglas automáticas, filas importadas, etc. Excluye los pedidos label-service y otros tipos que no son de entrega. Se omite en el flujo por lotes cuando el mismo destinatario tiene también order_create_async_postback_url configurado. Configure con order_create_webhook_url.order_status_change_webhook_urlSe dispara en cada transición de estado del pedido — recogido, en tránsito, entregado, excepción, cancelado. Configure con order_status_change_webhook_url.seguimiento_event_webhook_urlSe dispara en cada evento del ciclo de vida del seguimiento de un paquete (información enviada, inicio de entrega, entrega exitosa, no entregado, etc.). Configure con tracking_event_webhook_url. Los eventos de entrega y de recogida también incluyen la prueba de entrega: proof_files y proof_files_detail (file_id, type, url, full_url, URL de descarga firmada). Las fotos subidas después del evento llegan como pod.files_updated. Cada archivo incluye además el contexto de su evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) y service_status (1 = success / 2 = failed); en archivos antiguos sin evento registrado son null.order_create_async_postback_urlSe dispara una vez tras finalizar una importación masiva de pedidos. La carga contiene el array de resultados por fila. Configure con order_create_async_postback_url.pod_files_webhook_urlSe dispara cuando una foto de entrega o firma se añade, se reemplaza o se elimina (action: added / updated / removed) — un envío por archivo, sin más sondeo de adjuntos. Se activa configurando pod_files_webhook_url. Cada archivo incluye además el contexto de su evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) y service_status (1 = success / 2 = failed); en archivos antiguos sin evento registrado son null. Cuando el personal reemplaza una foto o firma, o establece una versión archivada como actual, el archivo se envía con action: updated y contiene solo la imagen actual; las versiones archivadas nunca se envían.order_deleted_webhook_urlSe dispara cuando un pedido se elimina permanentemente, para que su sistema pueda reflejar la eliminación. Se activa configurando order_deleted_webhook_url.order_cancel_failed_webhook_urlSe dispara cuando un intento de cancelación es rechazado (por ejemplo, el pedido ya está en reparto), para que su equipo de operaciones pueda supervisar las cancelaciones fallidas sin consultar la API. Se activa configurando order_cancel_failed_webhook_url.route_board_webhook_urlSe dispara cuando un asiento del tablero de rutas cambia de manos o el tablero cambia de estado — el campo action indica qué ocurrió (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Solo a nivel de empresa. Suscripción mediante route_board_webhook_url.device_order_webhook_urlEventos opcionales para los paquetes que gestionan sus taquillas inteligentes, quioscos y buzones inteligentes: un paquete depositado en una máquina, retirado, sacado por el personal o que ha superado su plazo de retirada, y las incidencias abiertas o resueltas sobre él. Solo aditivo: ningún webhook existente cambia y no se envía nada hasta que configure device_order_webhook_url.Todas las novedades de la API y los webhooks — cancelación idempotente, feeds de conciliación, firmas v2, nuevos eventos — con ejemplos listos para copiar. Todo totalmente retrocompatible.
Cada webhook saliente lleva una firma HMAC-SHA256 codificada en hexadecimal en el encabezado. Su receptor debe recalcular la firma sobre el cuerpo crudo con el secreto compartido y rechazar la solicitud si no coincide.
Cada URL de webhook puede recibir eventos en el formato nativo o como CloudEvents, y además puede llevar encabezados de firma de Standard Webhooks. Se configura por URL en los ajustes de webhook. Una URL sin configuración recibe los eventos exactamente como antes.
native — El cuerpo JSON y los encabezados descritos en esta página.ce_binary — El mismo cuerpo; los atributos de CloudEvents se envían como encabezados ce-*.ce_structured — El cuerpo es un CloudEvent (Content-Type: application/cloudevents+json) con el cuerpo nativo en data. Es idéntico en cada reintento y las firmas nativas lo cubren.ce-id y webhook-id llevan el event_id propio del evento cuando el cuerpo lo tiene; si no, X-Webhook-Event-Id. X-Webhook-Event-Id no cambia. ce-source y ce-srbusiness indican la empresa, también en los envíos a sus clientes.
Los webhooks de entregas en casilleros de socios y de entrega de terceros ofrecen la misma opción por endpoint, en la página de ajustes de webhook del proveedor. Las llamadas de planes de carga y de Open Platform la reciben por solicitud: callback_format y callback_signature, o callback.format y callback.signature. En ellos, ce-id y webhook-id son el identificador propio del evento (X-Webhook-Id, X-Webhook-Event-Id o X-Open-Delivery), ce-source indica la empresa que envía, y durante 24 horas tras una rotación de clave del proveedor webhook-signature lleva una firma por clave.
Los webhooks de conjuntos de datos ofrecen la misma opción por webhook, en el formulario del webhook y en su API (event_format y standard_signature). Standard Webhooks usa la clave secreta del webhook, por lo que necesita una. Las URL de los webhooks de conjuntos de datos deben ser direcciones HTTPS públicas.
Con Standard Webhooks, cada envío incluye además webhook-id, webhook-timestamp y webhook-signature. Se vuelven a firmar en cada reintento, por lo que un reintento queda dentro de una tolerancia de 5 minutos. La clave es su clave de firma de webhook en formato whsec_, que se muestra en la página de ajustes. Los encabezados nativos se siguen enviando.
Cada remitente firma de forma distinta. El nombre de encabezado X-Webhook-Signature lo usan tres remitentes con tres métodos distintos; verifique con el método del remitente que le llamó.
| Remitente | Encabezados | Firma |
|---|---|---|
| Webhooks de cliente (esta página) | Content-Type, Signature, X-Webhook-Event-Id, X-Webhook-Timestamp, X-Webhook-Signature-V2 |
Signature = hex(HMAC-SHA256(body))
X-Webhook-Signature-V2 = hex(HMAC-SHA256(timestamp + "." + body)) |
| Entregas en casilleros de socios | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature, X-Webhook-Test |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Asignaciones a entrega de terceros | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Llamadas de planes de carga | Content-Type, X-Webhook-Event-Id, X-Webhook-Event-Type, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| Llamadas de trabajos de Open Platform | Content-Type, X-Open-Event, X-Open-Delivery, X-Open-Job, X-Open-Timestamp, X-Open-Signature |
X-Open-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| OHP push | Content-Type, X-Ohp-Event, X-Ohp-Delivery, X-Ohp-Timestamp, X-Ohp-Signature |
|
| Webhooks de conjuntos de datos | Content-Type, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = hex(HMAC-SHA256(body)) |
| Webhooks de cliente con Standard Webhooks | webhook-id, webhook-timestamp, webhook-signature |
webhook-signature = "v1," + base64(HMAC-SHA256(webhook-id + "." + webhook-timestamp + "." + body)) |
Su proveedor de servicios puede ocultar sus precios a una cuenta de cliente, por familia de pedido (Entrega local, Servicio de etiquetas, Servicio de Envío, Servicio LTL, Servicios de almacenamiento, Servicios de mudanza, pedidos de dispositivo). Cuando eso le aplica, las entregas a su endpoint no llevan campos de precio: shipping_price, price_details, currency, impuestos, importes de recargos, precios de tarifas y similares se omiten en lugar de enviarse como cero. Las listas de tarifas conservan rate_id y los nombres de servicio para que aún pueda elegir uno.
Su endpoint debería responder con 2xx rápidamente. Si devuelve otra cosa, supera el tiempo de espera o no es accesible, se reintenta la entrega.
Pegue una carga que recibió de nosotros junto con el valor del encabezado Signature y su secreto — esta herramienta recalcula la firma en su navegador (nada sale de esta página) y le dice si coincide.
Dispare un webhook real y correctamente firmado desde nuestro servidor a una URL que proporcione. Úselo para probar que su receptor es accesible, que analiza la carga correctamente y que su lógica de verificación de firma funciona.
Vea los intentos de entrega de webhook más recientes en su cuenta — tanto eventos reales de producción como pruebas enviadas desde esta página. Pegue su Bearer token para cargar.
Los registros de entrega se conservan durante 90 días.
Un reenvío manual recibe un nuevo X-Webhook-Event-Id. Un event_id que lleva el propio evento (pod.files_updated, order.deleted, eventos de ciclo de vida y de pedidos de dispositivo) conserva su valor original.
| Tiempo | Evento | URL | Estado | HTTP | Intento | Tiempo (ms) | ¿Prueba? | Acciones |
|---|---|---|---|---|---|---|---|---|
| Aún no se han encontrado entregas de webhook. | ||||||||