Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.docketlayer.ai/llms.txt

Use this file to discover all available pages before exploring further.

Any GET /v2/case request can include a callback_url parameter. When supplied, DocketLayer delivers the full query result to that URL asynchronously, in addition to returning the synchronous HTTP response. This is useful for building event-driven pipelines: your agent or server receives the immediate response and a signed copy is pushed to your infrastructure without requiring you to poll.

​
How it works

GET /v2/case?case_id=1:24-cv-01234&court_code=nysd&last_checked=...&callback_url=https://yourapp.com/webhooks/docketlayer
  1. DocketLayer processes the query and returns the full response synchronously (200)
  2. Independently, DocketLayer POSTs the same result to your callback_url
  3. Your endpoint must respond 2xx to acknowledge receipt
  4. If your endpoint does not respond 2xx, DocketLayer retries up to 7 times
The synchronous response is not delayed by the callback delivery.

​
Callback payload

Your endpoint receives a POST with Content-Type: application/json: 
{
  "payload": {
    "meta": { "...standard meta block..." },
    "case_id": "1:24-cv-01234",
    "court_code": "nysd",
    "case": { "...case data..." },
    "delta": { "...delta block if last_checked was supplied..." }
  },
  "webhook": {
    "version": "2.0.0",
    "event_type": "case_query_complete",
    "date_created": "2026-04-29T12:00:00Z",
    "deprecation_date": null
  }
}
The payload object is identical to the synchronous response body.

​
Security headers

Every delivery includes these headers:
HeaderDescription
X-DocketLayer-SignatureHMAC-SHA256 of the raw request body: sha256=<hex>
X-DocketLayer-Signature-Key-IdID of the signing key used
X-DocketLayer-TimestampUnix timestamp of the delivery
Idempotency-KeyStable UUIDv4 unique to this delivery — same on every retry attempt
Always verify the signature before processing the payload. See the HMAC verification guide for implementation.

​
Retry schedule

DocketLayer retries failed deliveries (network errors, non-2xx responses) up to 7 times:
AttemptDelay after previous attempt
23 minutes
39 minutes
427 minutes
5~1.4 hours
6~4 hours
7~12 hours
After 7 failed attempts, the delivery is marked failed and no further retries occur. The total retry window is approximately 54 hours.

​
Delivery history

All delivery attempts are logged and queryable via GET /v2/wallet/deliveries. Use it to diagnose failures and confirm delivery. 
# Check recent failed deliveries
curl "https://api.docketlayer.ai/v2/wallet/deliveries?status=failed"

​
Receiving callbacks

Your endpoint should:
  1. Respond 2xx immediately — do not wait for processing to complete before responding, or DocketLayer may time out and retry
  2. Verify the X-DocketLayer-Signature header before trusting the payload
  3. Use Idempotency-Key to deduplicate retries — your endpoint may receive the same delivery more than once
from flask import Flask, request, abort
import hmac, hashlib, time

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["DOCKETLAYER_WEBHOOK_SECRET"]

@app.route("/webhooks/docketlayer", methods=["POST"])
def receive_callback():
    # Verify timestamp to prevent replay attacks
    timestamp = request.headers.get("X-DocketLayer-Timestamp", "0")
    if abs(time.time() - int(timestamp)) > 300:
        abort(400, "Timestamp out of range")

    # Verify signature
    raw_body = request.get_data()
    sig_header = request.headers.get("X-DocketLayer-Signature", "")
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, sig_header):
        abort(400, "Invalid signature")

    # Process payload
    data = request.json
    handle_docket_event(data["payload"])

    return "", 200

​
Notes

  • callback_url is supported on GET /v2/case only — not on /v2/monitor or batch
  • Per-query callback_url values in /v2/cases/batch work: each query in the batch can specify its own callback_url
  • Your callback endpoint must be reachable from the public internet — localhost URLs will not work in production
  • DocketLayer does not validate or pre-check the callback_url before making the query