Ir para o conteúdo

Webhook «sync concluído»

Quando a cadeia diária de sincronização termina (as fontes do INAPI e os passos derivados), o core envia um aviso assinado a cada integração inscrita: «o corpus do dia está pronto». Substitui a consulta periódica: ao recebê-lo, pergunte pelo que mudou (por exemplo, POST /annotations/search (MCP search_annotations) com detectedAfter = o detectedThrough do aviso anterior).

  • Um aviso por dia em que a cadeia roda (de segunda a sábado, hora do Chile; aos domingos não há cadeia nem aviso), no fim da cadeia completa (não um por fonte). É enviado mesmo se alguma fonte falhou: nesse caso ok é false e sources indica qual.
  • Igual para todos os inscritos. Não leva dados de nenhum cliente nem das marcas que cada um acompanha: só a data e a atualização do corpus.
  • O que não se sabe é omitido. Um campo ausente significa «não foi possível determinar»; nunca é preenchido com um valor aproximado.

Inscrição

Por enquanto a inscrição, o cancelamento e a rotação do segredo são feitos pelo operador no portal. Informe a URL (https://, pública) e guarde o segredo de assinatura (whsec_...): é mostrado uma única vez, na inscrição e na rotação. A rotação vale a partir do próximo envio, incluindo as novas tentativas.

Entrega de teste

Para testar o seu receptor sem esperar pela cadeia do dia, peça ao operador uma entrega de teste: sai na hora, assinada com o seu segredo atual, com os mesmos cabeçalhos de uma real mais X-Tarno-Test: true, e um X-Tarno-Delivery próprio (test-<uuid>).

  • Se já houve algum aviso, o corpo é o último aviso real, byte a byte (mesmo id): se você deduplica por id, não vai processá-lo duas vezes.
  • Se ainda não houve nenhum, o corpo é sintético e traz só o envelope: type, version, um id que começa com sync.finished:test: e "test": true. Nenhum dado do corpus.
  • É uma única tentativa, sem novas tentativas, e não conta como a entrega do dia: a real sai normalmente.

Ao ver X-Tarno-Test: true (ou "test": true no corpo), verifique a assinatura, responda 2xx e não faça mais nada.

A requisição

POST para a sua URL, content-type: application/json, com estes cabeçalhos:

Cabeçalho Valor
X-Tarno-Signature t=<unix>,v1=<hmac-hex>
X-Tarno-Event sync.finished
X-Tarno-Delivery id da entrega (o mesmo em cada nova tentativa)

Corpo (versão 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 O que é
id identificador do aviso; idempotência: se chegar duas vezes, processe uma
corpusDate dia do Chile da cadeia
dataAsOf fim da última execução correta das fontes de marcas (como em GET /system/freshness)
coverageThrough data de depósito até a qual o corpus está completo
detectedThrough use como detectedAfter na próxima consulta de mudanças
watchWatermark até onde as execuções corretas levaram o corpus (marca da vigilância)
sources o que rodou nesta cadeia, por fonte e tarefa, com as contagens

Verificar a assinatura

A mensagem assinada é `${t}.${rawBody}` com HMAC-SHA256 e o seu segredo (o mesmo formato que usava o webhook das watchlists, retirado em 2026-10-04). Rejeite se |agora − t| passar de 300 s e compare em tempo constante. Use o corpo bruto, sem reserializar.

Resposta e novas tentativas

Responda 2xx em menos de 10 s (processe depois). Qualquer outra resposta, um redirecionamento ou um erro de rede é tentado de novo após 1 min, 5 min, 15 min, 1 h e 4 h; após 6 tentativas falhas a entrega é abandonada. Avisos perdidos podem ser reconstruídos com GET /system/freshness e a consulta de mudanças.

  • Se o envio parar do nosso lado (o emissor cair), os dias que não saíram são enviados quando ele voltar, cada um com o seu corpusDate, até 7 dias para trás. Processe-os na ordem de corpusDate, não na de chegada.
  • Uma cadeia executada de novo no mesmo dia reescreve o seu aviso. Se a sua entrega desse dia ainda não tinha sido concluída, as novas tentativas já levam o corpo novo (mesmo id, p. ex. ok: true onde antes dizia ok: false). Uma entrega já concluída não se repete.