Asynchronous callbacks

Supply a callback_url to receive docket query results pushed to your server, in addition to the synchronous response.

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:

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:

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