Webhooks

Recibe eventos en tu servidor: registro de endpoints, verificación de firmas HMAC y política de reintentos.

Los webhooks avisan a tu servidor cuando cambia un recurso: por ejemplo, al comprar una guía, actualizar un rastreo o mover saldo. Registra un endpoint HTTPS y verifica la firma de cada entrega.

Registra un endpoint

Parámetros del cuerpo

curl -X POST https://api.sendit.mx/v1/webhook-endpoints \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mitienda.mx/webhooks/sendit",
    "description": "Receptor de producción",
    "events": ["shipment.label.created", "shipment.tracking.updated"]
  }'

{
  "success": true,
  "data": {
    "id": "whe_a1b2c3d4e5f6",
    "url": "https://mitienda.mx/webhooks/sendit",
    "description": "Receptor de producción",
    "events": ["shipment.label.created", "shipment.tracking.updated"],
    "status": "ACTIVE",
    "failureCount": 0,
    "disabledAt": null,
    "createdAt": "2026-07-18T10:00:00.000Z",
    "signingSecret": "whsec_9f8e7d6c5b4a"
  }
}

El campo se llama signingSecret. SendIt lo genera y lo devuelve solo al crear o rotar el endpoint. Guárdalo en un gestor de secretos: no puedes consultarlo de nuevo. El listado de endpoints nunca lo incluye.

Cada plan tiene un tope de endpoints activos. Registrar uno de más devuelve 403 PLAN_LIMIT_REACHED. Ver planes y cuotas.

Administra tus endpoints

Las lecturas las puede hacer cualquier miembro autenticado. Las escrituras requieren rol ADMIN y el alcance webhooks:write.

Tipos de evento

Puedes suscribirte a estos eventos documentados:

Suscribe cada endpoint solo a los eventos que le interesan. Tu handler debe ignorar los tipos que no reconozca.

El payload

{
  "id": "evt_1a2b3c4d5e",
  "type": "shipment.tracking.updated",
  "created": "2026-07-17T12:00:00.000Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "clxq1w2e3r4t5y6u7i8o9p0a",
      "status": "IN_TRANSIT",
      "trackingNumber": "1234567890",
      "carrierCode": "DHL",
      "organizationId": "clxorg123"
    }
  }
}

• created es una marca de tiempo ISO-8601, no segundos epoch.
• data.object es la proyección completa del recurso, no un subconjunto plano. Los eventos de envío traen dentro sus proyecciones de fromAddress, toAddress y label.
• No hay apiVersion ni organizationId en el nivel superior. El data.object de un envío sí trae su organizationId; el de un rastreador no.
• livemode: false marca los eventos de modo de prueba. Enrútalos a tu staging.
• id es único por evento. Úsalo para deduplicar si recibes una entrega repetida.

Verifica la firma

Cada entrega llega firmada con HMAC-SHA256 en el encabezado X-SendIt-Signature, con el formato t=<timestamp>,v1=<firma>:

POST /webhooks/sendit HTTP/1.1
X-SendIt-Signature: t=1752750000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Content-Type: application/json

Verifica siempre antes de procesar. La firma es la única prueba de que el evento viene de SendIt:

import crypto from "node:crypto";

function verifySenditSignature(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("="))
  );
  const { t, v1 } = parts;

  // 1. Rechaza timestamps viejos (protección contra replay)
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  // 2. Recalcula la firma sobre `${t}.${cuerpoCrudo}`
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // 3. Compara en tiempo constante
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Responde rápido, procesa después

Responde 2xx en cuanto persistas el evento, de preferencia en menos de un segundo. Procesa en segundo plano. Cualquier respuesta que no sea 2xx cuenta como fallo, incluidas las redirecciones.

Política de reintentos

Después del quinto intento el evento queda en EXHAUSTED y ya no se reintenta.

Un endpoint que falla continuamente durante 24 horas se deshabilita automáticamente. Cuando eso pasa, avisamos por correo a los administradores de la organización. Para reactivarlo, arregla tu servidor y manda una entrega de prueba con POST /v1/webhook-endpoints/:id/test: una prueba exitosa lo vuelve a habilitar.

Como las entregas pueden repetirse, haz tu procesamiento idempotente usando el id del evento.

Pruébalo sin riesgo

En modo de prueba, cada avance de estado dispara los webhooks reales con livemode: false. Compra una guía de prueba, avanza su estado y observa las entregas llegar a tu endpoint.

Errores