Webhooks

Objetivo #

Enterarse de lo que ocurre con un envío, en lugar de consultar la API cada pocos minutos. Trackberry envía una solicitud HTTPS firmada a una URL que usted elige, con el envío tal como queda justo después del cambio.

Los webhooks los administran los administradores y propietarios, en todos los planes, en Configuración → Tokens de API → Webhooks. Una organización puede tener hasta cinco endpoints.

Agregar un endpoint #

1. Abra Configuración → Tokens de API y elija Administrar webhooks.
2. Elija Agregar endpoint, escriba la URL, una descripción opcional y marque los eventos que desea. Se requiere al menos uno.
3. Abra el endpoint y muestre su secreto de firma. Guárdelo en un lugar seguro: su servidor lo usa para comprobar que una solicitud realmente proviene de Trackberry.
4. Elija Enviar evento de prueba y compruebe que su servidor lo recibió.

Eventos #

Las alertas son las que devuelve GET /api/v1/alerts. Un envío que aún espera aprobación, o uno que se identificó como de otra persona, no envía nada.

Cómo es una solicitud #

El cuerpo es JSON, con la forma del sobre de Standard Webhooks:

{
  "id": "evt_9f2c4e1b7a6d4c0f8e3b5a1d2c7e6f90",
  "type": "shipment.status_changed",
  "created_at": "2026-10-12T09:30:00Z",
  "api_version": "2026-10-01",
  "data": {
    "object": { "object": "shipment", "id": "shp_...", "status": "in_transit" },
    "previous_attributes": { "status": "validated" }
  }
}

• data.object es exactamente lo que devuelve GET /api/v1/shipments/:id (o lo que devuelve GET /api/v1/alerts para alert.created), en la versión de la API a la que está fijada su organización. api_version indica cuál.
• shipment.checks_completed agrega data.checks: un summary con el número de verificaciones por estado y results, una lista de { check_type, key, status }.
• id identifica el evento. Es el mismo para todos los endpoints, y el mismo en un reintento o un reenvío, así que úselo para ignorar duplicados.
• Los eventos pueden llegar más de una vez y fuera de orden. Compare marcas de tiempo como updated_at antes de sobrescribir datos más recientes.

Cada solicitud lleva estos encabezados:

Verificar la firma #

Verifique siempre antes de confiar en una solicitud. La firma es un HMAC-SHA256 de webhook-id.webhook-timestamp.cuerpo, con su secreto (decodificado de base64 y sin el prefijo whsec_). Las bibliotecas oficiales de Standard Webhooks lo hacen por usted y además rechazan marcas de tiempo antiguas.

Ruby, con la gema standardwebhooks:

require "standardwebhooks"

def receive(request)
  payload = request.body.read   # el cuerpo sin procesar, no el JSON ya interpretado
  headers = request.headers.to_h.slice("webhook-id", "webhook-timestamp", "webhook-signature")
  event = StandardWebhooks::Webhook.new(ENV.fetch("TRACKBERRY_WEBHOOK_SECRET")).verify(payload, headers)
  # event es el JSON interpretado; lanza StandardWebhooks::WebhookVerificationError si no es válido
end

Node, con el paquete standardwebhooks:

import { Webhook } from "standardwebhooks"

app.post("/webhooks/trackberry", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = new Webhook(process.env.TRACKBERRY_WEBHOOK_SECRET).verify(req.body, req.headers)
    // procese event.type
    res.sendStatus(204)
  } catch (err) {
    res.sendStatus(400)
  }
})

Use el cuerpo sin procesar. Un cuerpo que se interpretó y se volvió a serializar ya no coincide con la firma.

Entrega y reintentos #

Responda con cualquier código 2xx en menos de 10 segundos (dejamos de esperar a los 15 segundos en total). Cualquier otra cosa cuenta como fallo: otro código, un tiempo de espera agotado, un error de conexión y una redirección (nunca seguimos redirecciones, así que indique la URL final). Trackberry lee y conserva solo los primeros 2 KB de su respuesta y los muestra en la página del endpoint.

Una entrega fallida se reintenta hasta 8 veces en total: de inmediato y luego después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 10 horas, aproximadamente un día en total. Cada intento queda registrado en la página del endpoint durante 30 días, y Reenviar envía el mismo evento de nuevo con una marca de tiempo nueva.

Si las entregas a un endpoint siguen fallando durante más de 3 días, Trackberry lo desactiva, descarta las entregas que seguían en espera y envía un correo a los administradores de su organización. La cuenta solo avanza mientras sigan llegando fallos: un éxito, o un día sin ninguna entrega fallida, la reinicia. Cuando corrija su servidor, abra el endpoint y elija Reactivar endpoint.

Enviar evento de prueba envía el evento una sola vez y nunca lo reintenta. Una prueba fallida no cuenta para desactivar el endpoint. Una entrega que se perdió de nuestro lado, por ejemplo durante un despliegue, se recupera y se envía de nuevo en menos de una hora.

Seguridad y red #

• Los endpoints deben usar HTTPS y ser accesibles desde internet público. Rechazamos las URL cuyo host se resuelve a una dirección privada, de loopback, de enlace local, compartida o reservada, IPv6 incluido, tanto al guardar el endpoint como antes de cada entrega. También rechazamos trackberry.com y sus subdominios.
• Nos conectamos a la dirección que verificamos, así que un cambio de DNS entre la verificación y la conexión no puede enviar una solicitud a otro lugar.
• No publicamos direcciones IP de origen fijas, así que no dependa de una lista de IP permitidas. La firma es lo que le indica que una solicitud es nuestra.
• Para reemplazar un secreto filtrado, elija Renovar secreto. El anterior deja de funcionar de inmediato (no hay periodo de solapamiento), así que actualice su servidor al mismo tiempo.

Solución de problemas #