Saltar a contenido

Webhook «sync terminado»

Cuando termina la cadena diaria de sincronización (las fuentes de INAPI y los pasos derivados), el core envía un aviso firmado a cada integración suscrita: «el corpus del día está listo». Sustituye al sondeo periódico: al recibirlo, pregunta por lo que cambió (por ejemplo, POST /annotations/search (MCP search_annotations) con detectedAfter = el detectedThrough del aviso anterior).

  • Un aviso por día que corre la cadena (de lunes a sábado, hora de Chile; los domingos no hay cadena ni aviso), al final de la cadena completa (no uno por fuente). Sale también si alguna fuente falló: en ese caso ok es false y sources dice cuál.
  • Igual para todos los suscriptores. No lleva datos de ningún cliente ni de las marcas que sigue cada uno: sólo la fecha y la frescura del corpus.
  • Lo que no se sabe se omite. Un campo ausente significa «no se pudo determinar»; nunca se rellena con un valor aproximado.

Alta

Hoy el alta, la baja y la rotación del secreto las hace el operador desde el portal. Pide la URL (https://, pública) y guarda el secreto de firma (whsec_...): se muestra una sola vez, al dar de alta y al rotar. Una rotación vale desde el siguiente envío, reintentos incluidos.

Entrega de prueba

Para comprobar tu receptor sin esperar a la cadena del día, pide al operador una entrega de prueba: sale al momento, firmada con tu secreto actual, con las mismas cabeceras que una real más X-Tarno-Test: true, y un X-Tarno-Delivery propio (test-<uuid>).

  • Si ya hubo algún aviso, el cuerpo es el último aviso real, byte a byte (mismo id): si deduplicas por id, no lo procesarás dos veces.
  • Si aún no hubo ninguno, el cuerpo es sintético y sólo trae el envoltorio: type, version, un id que empieza por sync.finished:test: y "test": true. Ningún dato del corpus.
  • Es un solo intento, sin reintentos, y no cuenta como la entrega del día: la real sale igual.

Si ves X-Tarno-Test: true (o "test": true en el cuerpo), verifica la firma, contesta 2xx y no hagas nada más.

La petición

POST a tu URL, content-type: application/json, con estas cabeceras:

Cabecera Valor
X-Tarno-Signature t=<unix>,v1=<hmac-hex>
X-Tarno-Event sync.finished
X-Tarno-Delivery id de la entrega (el mismo en cada reintento)

Cuerpo (versión 1):

{
  "type": "sync.finished",
  "version": 1,
  "id": "sync.finished:2026-10-02",
  "corpusDate": "2026-10-02",
  "chainStartedAt": "2026-10-02T15:00:04.000Z",
  "finishedAt": "2026-10-02T17:41:10.000Z",
  "ok": true,
  "syncExitCode": 0,
  "dataAsOf": "2026-10-02T16:02:31.000Z",
  "coverageThrough": "2026-09-30",
  "detectedThrough": "2026-10-02T17:41:09.000Z",
  "watchWatermark": "2026-10-02T15:58:12.000Z",
  "sources": [
    { "source": "estado_diario", "task": "boletin_tipo2", "runs": 1, "failedRuns": 0,
      "processed": 412, "changed": 380, "quarantined": 0, "lastFinishedAt": "2026-10-02T15:06:40.000Z" }
  ]
}
Campo Qué es
id identificador del aviso; idempotencia: si llega dos veces, procésalo una
corpusDate día de Chile de la cadena
dataAsOf fin de la última corrida correcta de las fuentes de marcas (igual que en GET /system/freshness)
coverageThrough fecha de presentación hasta la que el corpus está completo
detectedThrough úsalo como detectedAfter en tu próxima consulta de cambios
watchWatermark hasta dónde dejaron el corpus las corridas correctas (marca de la vigilancia)
sources qué corrió en esta cadena, por fuente y tarea, con sus recuentos

Verificar la firma

El mensaje firmado es `${t}.${rawBody}` con HMAC-SHA256 y tu secreto (el mismo formato que usaba el webhook de las watchlists, retirado el 2026-10-04). Rechaza si |ahora − t| supera 300 s y compara en tiempo constante. Usa el cuerpo crudo, sin volver a serializarlo.

Respuesta y reintentos

Contesta 2xx en menos de 10 s (procesa después). Cualquier otra respuesta, una redirección o un error de red se reintenta a 1 min, 5 min, 15 min, 1 h y 4 h; tras 6 intentos fallidos la entrega se da por perdida. Los avisos que no hayas recibido se pueden reconstruir con GET /system/freshness y la consulta de cambios.

  • Si el envío se interrumpe de nuestro lado (una caída del emisor), los días que no salieron se envían al volver, con su corpusDate de entonces, hasta 7 días atrás. Procésalos en el orden de corpusDate, no en el de llegada.
  • Una cadena que se vuelve a correr el mismo día reescribe su aviso. Si tu entrega de ese día aún no se había completado, los reintentos llevan ya el cuerpo nuevo (mismo id, p. ej. ok: true donde antes decía ok: false). Una entrega ya completada no se repite.