Webhooks de tracking

Última actualización: 2026-09-21 · Base URL: https://api.shalom-api.lat

En lugar de consultar el estado en bucle, registra tu URL y suscribe las guías que te interesan. Cuando el estado cambia, la plataforma envía un POST JSON firmado con HMAC-SHA256 (formato tipo Stripe), con reintentos automáticos y deduplicación por ID de evento. Tu endpoint solo tiene que validar la firma y responder 200.

PUT/webhooks

Configurar webhook

Registra la URL de webhook de la cuenta y genera un secreto de firma. El secreto se devuelve completo solo aquí. Usa rotateSecret=true para rotarlo.

Parámetro	Descripción
url*	URL destino (formato uri, https recomendado).
rotateSecret	Regenerar el secreto de firma (boolean, default false).

{
  "url": "https://tu-servidor.com/webhooks/shalom"
}

Respuesta (ejemplo)

{
  "success": true,
  "message": "Webhook configurado.",
  "webhook": {
    "url": "https://tu-servidor.com/webhooks/shalom",
    "secret": "whsec_...",
    "enabled": true
  }
}

Nota: El secreto solo se devuelve completo en esta respuesta; en GET se muestra enmascarado.

GET/webhooks

Consultar webhook

Devuelve la configuración de webhook de la cuenta (secreto enmascarado).

curl -X GET "https://api.shalom-api.lat/webhooks" \
  -H "x-api-key: TU_API_KEY"

Respuesta (ejemplo)

{
  "success": true,
  "configured": true,
  "webhook": {
    "url": "https://tu-servidor.com/webhooks/shalom",
    "enabled": true,
    "secretPreview": "whsec_9f2b7c…"
  }
}

Nota: Si no hay webhook configurado: { success: true, configured: false, webhook: null }.

DELETE/webhooks

Eliminar webhook

Elimina la configuración de webhook de la cuenta.

curl -X DELETE "https://api.shalom-api.lat/webhooks" \
  -H "x-api-key: TU_API_KEY"

Respuesta (ejemplo)

{
  "success": true,
  "message": "Webhook eliminado."
}

POST/tracking/subscriptions

Suscribir a cambios de tracking

Suscribe la cuenta a los cambios de estado de un envío. Registra el envío en el sistema de tracking en background y notifica vía webhook cuando cambie de estado.

Parámetro	Descripción
orderNumber*	Número de guía (8 dígitos, patrón ^[0-9]+$).
orderCode*	Código de seguridad (4 caracteres).

{
  "orderNumber": "66479331",
  "orderCode": "3KTH"
}

Respuesta (ejemplo)

{
  "success": true,
  "message": "Suscripción creada.",
  "subscription": {
    "id": "5f4e3d2c-1b0a-9988-7766-554433221100",
    "orderNumber": "66479331",
    "orderCode": "3KTH",
    "lastStatus": null,
    "active": true,
    "createdAt": "2026-09-08T12:00:00.000Z"
  }
}

GET/tracking/subscriptions

Listar suscripciones

Lista las suscripciones de tracking de la cuenta.

curl -X GET "https://api.shalom-api.lat/tracking/subscriptions" \
  -H "x-api-key: TU_API_KEY"

Respuesta (ejemplo)

{
  "success": true,
  "total": 1,
  "data": [
    {
      "id": "5f4e3d2c-1b0a-9988-7766-554433221100",
      "orderNumber": "66479331",
      "orderCode": "3KTH",
      "lastStatus": "IN_TRANSIT",
      "active": true,
      "createdAt": "2026-09-08T12:00:00.000Z"
    }
  ]
}

DELETE/tracking/subscriptions

Cancelar suscripción

Cancela la suscripción de la cuenta a un envío.

Parámetro	Descripción
orderNumber*	Número de guía (8 dígitos, querystring).
orderCode*	Código de seguridad (4 caracteres, querystring).

curl -X DELETE "https://api.shalom-api.lat/tracking/subscriptions?orderNumber=66479331&orderCode=3KTH" \
  -H "x-api-key: TU_API_KEY"

Respuesta (ejemplo)

{
  "success": true,
  "message": "Suscripción eliminada."
}

Qué resuelve un webhook

La alternativa es preguntar cada pocos segundos por cada guía. Un webhook invierte eso: registras tu URL una vez, suscribes las guías que te interesan y recibes un POST cuando algo cambia de verdad.

Es la diferencia entre enterarte de una entrega en el momento y enterarte la próxima vez que alguien consulte.

Verifica siempre la firma

PUT /webhooks devuelve un secreto con el que se firma cada envío. Comprueba esa firma antes de procesar nada: sin eso, cualquiera que conozca tu URL puede inyectarte eventos falsos.

Si el secreto se filtró, vuelve a llamar a PUT /webhooks con rotateSecret en true y actualiza tu verificación.

Suscribir guías una por una

POST /tracking/subscriptions se hace por guía, con su orderNumber y su orderCode. Si tu tienda registra muchos envíos, suscribe justo después de crear cada guía, en el mismo flujo.

Responde rápido y de forma idempotente

Contesta con un 2xx en cuanto recibas y procesa el evento después. Si tu endpoint tarda o falla, el sistema reintenta, así que guarda un identificador del evento para no aplicar dos veces el mismo cambio de estado.

Cuándo seguir usando polling

Si solo necesitas el estado cuando el cliente abre la pantalla de seguimiento, una consulta puntual por API es más simple que montar un endpoint público. El webhook tiene sentido cuando algo tiene que pasar sin que nadie esté mirando.

Errores de esta sección

400	URL de webhook inválida o guía mal formada.
401	Falta autenticación de usuario.

Preguntas frecuentes

¿Cómo compruebo que el POST viene de Shalom API y no de un tercero?

Verificando la firma HMAC con el secreto que devuelve PUT /webhooks. Es el paso que impide que alguien inyecte eventos falsos en tu sistema.

¿Necesito HTTPS para recibir webhooks?

La URL debe ser válida y se recomienda HTTPS, porque por ahí viajan datos de tus envíos.

¿Puedo cambiar la URL del webhook?

Sí, volviendo a llamar a PUT /webhooks con la nueva url.

¿Cómo dejo de recibir eventos de una guía?

Con DELETE /tracking/subscriptions, enviando su orderNumber y su orderCode.

¿Qué pasa si mi servidor está caído cuando llega un evento?

El sistema reintenta. Por eso conviene responder rápido y procesar de forma idempotente, para que un reintento no duplique el efecto.

Continúa con

Consultar estado puntual por API Cómo reintenta la plataforma

¿Aún no tienes API key?

Escríbenos por WhatsApp y la recibes de inmediato para probar todos estos ejemplos.

Solicitar API key