Asynchronous callbacks

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

DocketLayer processes the query and returns the full response synchronously (200)
Independently, DocketLayer POSTs the same result to your callback_url
Your endpoint must respond 2xx to acknowledge receipt
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:

Header	Description
`X-DocketLayer-Signature`	HMAC-SHA256 of the raw request body: `sha256=<hex>`
`X-DocketLayer-Signature-Key-Id`	ID of the signing key used
`X-DocketLayer-Timestamp`	Unix timestamp of the delivery
`Idempotency-Key`	Stable 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:

Attempt	Delay after previous attempt
2	3 minutes
3	9 minutes
4	27 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:

Respond 2xx immediately — do not wait for processing to complete before responding, or DocketLayer may time out and retry
Verify the X-DocketLayer-Signature header before trusting the payload
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

Getting started

API reference

Concepts

Guides

Integration quickstarts

Resources

Asynchronous callbacks

How it works

Callback payload

Security headers

Retry schedule

Delivery history

Receiving callbacks

Notes

​How it works

​Callback payload

​Security headers

​Retry schedule

​Delivery history

​Receiving callbacks

​Notes

How it works

Callback payload

Security headers

Retry schedule

Delivery history

Receiving callbacks

Notes