Skip to content

"Sync finished" webhook

When the daily sync chain finishes (INAPI's sources and the derived steps), the core sends one signed notice to every subscribed integration: "today's corpus is ready". It replaces periodic polling: when you get it, ask for what changed (for example POST /annotations/search (MCP search_annotations) with detectedAfter = the detectedThrough of the previous notice).

  • One notice per day the chain runs (Monday to Saturday, Chile time; there is no chain and no notice on Sundays), at the end of the whole chain (not one per source). It is sent even when a source failed: then ok is false and sources says which one.
  • The same for every subscriber. It carries no client data and nothing about the marks each one follows: only the date and freshness of the corpus.
  • Unknown values are omitted. A missing field means "could not be determined"; it is never filled with an approximate value.

Subscribing

For now the operator subscribes, unsubscribes and rotates the secret from the operator portal. Provide the URL (https://, public) and keep the signing secret (whsec_...): it is shown only once, on subscription and on rotation. A rotation applies from the next send, retries included.

Test delivery

To check your receiver without waiting for the day's chain, ask the operator for a test delivery: it is sent right away, signed with your current secret, with the same headers as a real one plus X-Tarno-Test: true, and its own X-Tarno-Delivery (test-<uuid>).

  • If there has been a notice already, the body is the latest real notice, byte for byte (same id): if you deduplicate by id, you will not process it twice.
  • If there has been none yet, the body is synthetic and carries only the envelope: type, version, an id starting with sync.finished:test: and "test": true. No corpus data.
  • It is a single attempt, with no retries, and it does not count as the day's delivery: the real one is sent as usual.

When you see X-Tarno-Test: true (or "test": true in the body), verify the signature, answer 2xx and do nothing else.

The request

POST to your URL, content-type: application/json, with these headers:

Header Value
X-Tarno-Signature t=<unix>,v1=<hmac-hex>
X-Tarno-Event sync.finished
X-Tarno-Delivery delivery id (the same on every retry)

Body (version 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" }
  ]
}
Field Meaning
id notice id; idempotency: if it arrives twice, process it once
corpusDate Chile calendar day of the chain
dataAsOf end of the last successful run of the trademark sources (as in GET /system/freshness)
coverageThrough filing date up to which the corpus is complete
detectedThrough use it as detectedAfter in your next change query
watchWatermark how far the successful runs advanced the corpus (watch watermark)
sources what ran in this chain, per source and task, with its counts

Verifying the signature

The signed message is `${t}.${rawBody}` with HMAC-SHA256 and your secret (the same format the watchlists webhook used before it was retired on 2026-10-04). Reject when |now − t| exceeds 300 s and compare in constant time. Use the raw body, never re-serialized.

Response and retries

Answer 2xx within 10 s (process afterwards). Any other response, a redirect or a network error is retried after 1 min, 5 min, 15 min, 1 h and 4 h; after 6 failed attempts the delivery is given up. Missed notices can be rebuilt from GET /system/freshness and the change query.

  • If sending stops on our side (the sender is down), the days that did not go out are sent when it comes back, each with its own corpusDate, up to 7 days back. Process them in corpusDate order, not in arrival order.
  • A chain re-run on the same day rewrites its notice. If your delivery for that day had not completed yet, the retries already carry the new body (same id, e.g. ok: true where it said ok: false). A completed delivery is not repeated.