Documentation Index
Fetch the complete documentation index at: https://docs.judit.io/llms.txt
Use this file to discover all available pages before exploring further.
Cached response (
cached_response)When you create a lawsuit or historical query, Judit first checks whether the data already exists in our database. If it does, we return the result immediately — both in the API response and via webhook (if registered) — with the field cached_response: true.In parallel, Judit triggers a fresh fetch against the courts. If anything has changed, you receive a second response with cached_response: false. That is the most up-to-date result.This is why it is normal to receive two seemingly identical webhooks for the same request_id:- The first one comes from cache (
cached_response: true) - The last one is the updated result (
cached_response: false)
POST the response object to your configured URL. It’s the most efficient and cheapest way to integrate asynchronous flows.
🤖 Delivery pattern: HTTP POST withapplication/json. Use a public HTTPS URL. Implement idempotency based onrequest_id+cached_response. On 5xx or timeout, we retry with backoff.
When to use
Async at scale
For high volumes (hundreds/thousands of requests), webhooks eliminate polling and dramatically reduce your quota usage.
Tracking notifications
Get notified the moment a tracker detects a new step or a new lawsuit is born.
Internal-system integration
Queue → handler → ERP/CRM/BI: event-driven pattern without polling Judit.
Cache vs. update identification
Use
cached_response to distinguish the initial (cache) response from the later (court-fresh) one.How it works
For each event wePOST HTTPS to your URL with application/json. Delivery is incremental — you may receive several responses for the same request_id before the request_completed event signals the end of the flow.
Configuring your webhook
There are two ways to receive callbacks:1. Account-wide (recommended)
Register a single URL that receives every callback (queries + tracking). Request via Support — takes minutes.
2. Per-request
Add
callback_url in the request payload. Useful for dynamic routing (e.g. webhook per environment or per end-customer).The
with_attachments parameter applies only to lawsuit queries (search_type: "lawsuit_cnj").Events delivered
event_type | Fires when | Payload |
|---|---|---|
response_created | Every time a new response_data is generated for the request (cache or court) | lawsuit, entity, warrant or execution object |
request_completed | End of the request flow (all courts responded) | Final request object with status: "completed" |
tracking_response | Fired by trackers (each new movement detected) | Same shape as response_created, but via tracking_id |
callback_id— unique delivery id (use for idempotency).reference_id— therequest_idortracking_idthat originated the event.payload— content (lawsuit, registration data, etc.).
cached_response: reading the two deliveries
Most requests produce two deliveries in sequence: one from cache, one from the live court. Use cached_response to identify.
| Sequence | event_type | cached_response | Meaning |
|---|---|---|---|
| 1 | response_created | true | Came from Judit’s datalake (fast initial response). |
| 2 | response_created | false | Live fetch from the court. Always the definitive version when present. |
| 3 | request_completed | — | All courts responded. Your app can close the loop. |
⚠️ For lawsuits recently refreshed (withincache_ttl_in_days), you may receive only thecached_response: truedelivery — no live fetch happens because the cache is still valid.
Best practices (production-grade)
✅ Idempotency
✅ Idempotency
Use
callback_id as the idempotency key: drop duplicates based on it. On retries, the same callback_id is redelivered.✅ Reply fast (HTTP 2xx)
✅ Reply fast (HTTP 2xx)
✅ Persist the event before processing
✅ Persist the event before processing
Production pattern: write the raw event into a queue/log and process later. Avoids loss on application errors.
✅ Treat `cached_response: true` as provisional
✅ Treat `cached_response: true` as provisional
Always treat the
cached_response: false delivery (when it exists) as the final version. Your UI/reports should reflect the latest value.✅ Validate source (HTTPS + IP allowlist)
✅ Validate source (HTTPS + IP allowlist)
Accept
POST only from Judit IPs (ask support for the list). Always HTTPS. In regulated environments also validate the User-Agent header.✅ Implement tolerant retry
✅ Implement tolerant retry
On 5xx or timeout we retry with exponential backoff. If your URL stays down for too long, events are lost — keep the endpoint stable.
Webhook receiver (Node.js example)
Python (FastAPI)
Webhook delivery request
When a search or tracking is performed through the JUDIT API, we send back a response with the information found. To ensure that all responses are delivered to a single webhook, registration must be done by contacting our Support. Alternatively, the webhook can also be specified by adding the callback_url parameter to the request payload, as shown in the example below:The “with_attachments” parameter should only be used for lawsuit queries, that is, when the “search_type” field is set to “lawsuit_cnj”.
Response delivery
We send a POST request to the webhook, delivering responses based on your search results. Delivery happens incrementally, as responses are generated, and is completed when the request status is updated to “completed”.⚠️ In some cases, the
cached_response field may be true and still be the only response sent. This happens when the lawsuit query was performed recently, making a new capture from the court unnecessary.Response for historical query:
Example response withcached_response: true:
See response example
See response example
cached_response: false:
See response example
See response example
Response for lawsuit query:
Example response withcached_response: true:
See response example
See response example
cached_response: false:
See response example
See response example