01 / Guía
Qué resuelve un webhook de rastreo
Un webhook conecta el cambio del paquete con una acción de negocio. Cuando llega un evento, tu sistema puede actualizar el pedido sin esperar a que una persona abra el portal de la paquetería.
Empieza con pocas acciones y hazlas predecibles. Mostrar el nuevo estado, guardar la hora del cambio y señalar una incidencia suele ser una primera versión suficiente.
Actualizar el estado del pedido dentro de tu ecommerce o sistema.
Informar al equipo cuando un envío necesita atención.
Preparar mensajes para el cliente desde una fuente común.
Medir el recorrido sin consultar cada paquetería por separado.
02 / Guía
El recorrido de un cambio de estado
La integración tiene cuatro responsabilidades claras. SendIt entrega el evento; tu receptor comprueba su origen, decide si ya lo procesó y aplica la acción correspondiente en tu sistema.
- 01
Cambia el envío
SendIt registra un nuevo estado normalizado.
- 02
Llega el webhook
Tu URL recibe el evento y sus encabezados firmados.
- 03
Verificas y deduplicas
Compruebas la firma y el identificador del evento.
- 04
Actualizas el pedido
Tu sistema guarda el estado y ejecuta la acción necesaria.
03 / Guía
Los dos eventos que importan para el seguimiento
Las guías compradas en SendIt notifican los cambios con shipment.tracking.updated. Un número externo registrado mediante un tracker utiliza tracker.updated.
No existe un evento separado para cada resultado final. Para saber si el paquete está entregado o tiene una incidencia, lee data.object.status dentro del evento de actualización.
shipment.tracking.updated: cambios de estado de una guía creada en SendIt.
tracker.updated: cambios de una guía externa registrada para seguimiento.
data.object.status: estado normalizado que debe actualizar tu pedido.
livemode: separa los eventos de prueba de los eventos de operación.
04 / Guía
Verifica la firma antes de confiar en el evento
Cada entrega incluye X-SendIt-Signature. La firma se calcula con el secreto de tu endpoint, la marca de tiempo y los bytes originales del cuerpo. Verifica esos bytes antes de convertir el JSON.
El secreto de firma se muestra cuando creas o rotas el endpoint. Guárdalo en tu gestor de secretos y nunca lo expongas en el navegador ni en el repositorio.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifySendItWebhook(
rawBody: Buffer,
signatureHeader: string,
secret: string,
toleranceSeconds = 300,
) {
const parts = Object.fromEntries(
signatureHeader.split(",").map((part) => part.split("=", 2)),
);
const timestamp = Number(parts.t);
if (!Number.isFinite(timestamp) ||
Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
throw new Error("Webhook timestamp outside tolerance");
}
const expected = createHmac("sha256", secret)
.update(parts.t + ".")
.update(rawBody)
.digest();
const received = Buffer.from(parts.v1 ?? "", "hex");
if (expected.length !== received.length ||
!timingSafeEqual(expected, received)) {
throw new Error("Invalid webhook signature");
}
return JSON.parse(rawBody.toString("utf8"));
}05 / Guía
Una lista corta para operarlo bien
Una firma válida solo confirma el origen. Tu integración también debe soportar reintentos y evitar que el mismo evento produzca dos acciones.
Usa el webhook como aviso y consulta el recurso de la API cuando una decisión necesite el estado más reciente. Eso mantiene el pedido correcto aunque tu receptor haya estado temporalmente fuera de línea.
- 01
Conserva el cuerpo original
Lee los bytes sin reserializar antes de verificar la firma.
- 02
Guarda el ID del evento
Si el mismo id vuelve a llegar, responde correctamente sin repetir la acción.
- 03
Separa prueba y operación
Usa livemode para impedir que un evento de prueba modifique pedidos reales.
- 04
Responde rápido
Devuelve una respuesta 2xx y procesa el trabajo más pesado fuera de la recepción.
- 05
Reconcilia lo importante
Consulta la API cuando necesites confirmar el estado actual del envío.
06 / Guía
Cómo encaja en una integración con SendIt
SendIt utiliza el mismo vocabulario de estados para guías creadas en la plataforma y trackers externos. Tu ecommerce puede traducir ese estado una sola vez y conservar la misma experiencia aunque cambie la paquetería.
La plataforma está en pre-lanzamiento. Puedes revisar el contrato de webhooks, probar eventos sin tocar una operación real y preparar el receptor antes de la apertura.
Siguiente paso
Completa la tarea.
Preguntas frecuentes
Respuestas rápidas.
¿Qué evento recibo cuando un paquete se entrega?
Recibes shipment.tracking.updated para una guía de SendIt o tracker.updated para una guía externa. El resultado, incluido DELIVERED, aparece en data.object.status.
¿Un webhook puede llegar más de una vez?
Sí. La entrega admite reintentos, por lo que debes guardar el id del evento y evitar repetir la misma acción.
¿Debo confiar en cualquier solicitud que llegue a mi URL?
No. Verifica X-SendIt-Signature contra el cuerpo original y el secreto del endpoint antes de interpretar el evento.
¿Puedo probar el receptor sin afectar pedidos reales?
Sí. Los eventos de prueba llevan livemode: false para que tu integración los mantenga separados de la operación real.
¿El webhook reemplaza una consulta a la API?
No en todos los casos. Úsalo para reaccionar al cambio y consulta la API cuando una decisión necesite confirmar el estado más reciente.