Webhook API

CourtListener’s webhook system allows us to push information to you, enabling bi-directional APIs without polling.

To set this up, you create a URL on your server where CourtListener can send data. Then, whenever something important happens in CourtListener, we will POST an “event” to that URL as JSON data. When you receive the event, you can process it and perform whatever actions your system needs in response.

Currently, CourtListener can send webhook events whenever dockets are updated, search alerts are triggered, docket alerts expire, or when RECAP Fetch tasks complete. If you have other events of interest, please get in touch.

Pricing

CourtListener is hosted by Free Law Project, a non-profit that has "Free" in its name, but we do charge reasonable fees to organizations using advanced features like Webhooks and APIs. We use these fees to maintain our paid and free services.

When we see an organization starting a new project using Webhooks, we will get in touch to discuss the project and set up an agreement that works for everybody.

Questions? Get in touch to start the conversation.

Contact Us

Getting Started With Webhooks

Creating your first webhook working can be complicated. To get an overview of the process, please read our documentation on getting started.

Get Started

Overview of Events

Standard Headers

Each webhook event contains two HTTP headers with additional context for the event:

• Content-Type: Indicates the content type of the payload request. For now, our events only support "application/json".

• Idempotency-Key: This is a unique 128 bit UUID that corresponds to each event. This value should be used by your application to ensure that you do not process events more than once.

  If you do not take advantage of this feature, we may resend an event that appeared to fail, and you may receive and process it multiple times. More details about this are available in the section on retries below.

Standard Fields

Each webhook event is a JSON hash with two keys, payload and webhook. The payload key contains the specific data for the event that occurred. Its values are described in the event-specific descriptions below.

The webhook key helps with maintenance and compatibility. It contains information about the webhook itself. This key should be monitored by administrators and used to track the deprecation schedule for the webhook events.

It has the following structure:

Webhook Security

Our webhook events will be sent from one of two IP addresses:

1. 34.210.230.218
2. 54.189.59.91

We recommend adding these IP addresses to your network allow list and/or verifying that the webhook events you receive come from these addresses.

We also recommend you protect your webhook endpoints by giving them long, random, secret URLs instead of short preditable ones.

Beyond this, our webhook system does not have an authentication mechanism to verify that a POST to your endpoint came from CourtListener. The decision not to support an authentication mechanism was made after analyzing the risk of lacking authentication and after completing a review of the Stripe payments platform (which defaults to not using authentication despite being a high-risk environment).

If the need for webhook authentication is a blocker for your organization, please let us know and we can revisit this decision.

Retries and Automatic Endpoint Disablement

Errors across distributed systems are inevitable. To make our webhook system resilient, we automatically retry events POSTed to your application that do not receive a 2xx status code response within one second.

Events are retried up to seven times after the first failure. The retry logic uses an exponential backoff starting at roughly three minutes with a 3× multiplier. As shown in the table below, this gives you around 54 hours to fix any issues in your system.

The next attempt date and time for a specific event can be found in your webhook logs.

As webhooks fail to be delivered, we will send emails to your account to inform you of the issue. Email notifications are sent per webhook endpoint based on the first failing event for that endpoint — Notifications are not sent for every failing event, since that would flood your inbox.

This table explains the retry and notification schedule for failing events (in minutes):

After a webhook fails eight times, it is disabled in our system and we immediately stop sending it new or undelivered events.

At that point, you will have received two warning emails about the issue, and a third informing you that the endpoint is disabled. Webhooks can be re-enabled at any time, but will get disabled again if errors continue.

Fixed webhook endpoints can be re-enabled in the webhooks panel.

Once your webhook endpoint is re-enabled, we will continue attempting to deliver failed webhook events that we stopped retrying when the endpoint was disabled, if those events occurred within the last two days.

Event Types

Docket Alert Events

If you wish to receive events when particular dockets are updated in CourtListener, you must first “subscribe” to dockets.

A docket subscription can be created in one of three ways:

1. For normal users, the best way is via the CourtListener website itself.

2. For servers, the best way is to use the Docket Alert API.

   For example, this shell code searches for the Trump Mar-A-Lago case and then subscribes your account to it:

   curl --silent \ --url 'https://www.courtlistener.com/api/rest/v3/search/?type=d&docket_number=22-cv-81294&case_name=trump' \ --header 'Authorization: Token <your-token-here>' | \ jq '.results[0].docket_id' | \ xargs -I % curl -X POST \ --url 'https://www.courtlistener.com/api/rest/v3/docket-alerts/' \ --header 'Authorization: Token <your-token-here>' \ --data 'docket=%' 

3. For users of @recap.email, the best way to subscribe to a case is to have auto-subscribe turned on in your settings.

   When auto-subscribe is on, you will automatically be subscribed to cases when we receive your PACER notifications for them. For users that wish to subscribe to all the cases for which they get PACER notifications, this is usually the best way to do so.

Once subscribed to a case, we will begin POSTing events to your Docket Alert webhook endpoint whenever that case gets new filings.

The docket alert event is a JSON hash with two keys, webhook and payload. payload has a key for new filings that is called results.

The shape of the data is thus:

 { "payload": { "results": [...] }, "webhook": {...} } 

The results key is based on the Docket Entry API. It has all the same fields except for the resource_uri and tags fields, which are omitted, and the docket field is an ID instead of a URL. If you already have access to that API, you can see an example object here, and do an HTTP OPTIONS request to get a description of the fields:

curl -X OPTIONS \ --url 'https://www.courtlistener.com/api/rest/v3/docket-entries/' \ --header 'Authorization: Token <your-token-here>'

If you do not yet have access to the Docket Entry API, please let us know. In the meantime, another way to see an example event is via the webhook testing tool.

Search Alert Events

Search alerts in CourtListener allow you to subscribe to a particular query so that you are sent a webhook event whenever it has new results. For example, you can use search alerts to get a notification whenever a case is cited or whenever a particular keyword appears in a legal decision.

To get search alert events, begin by subscribing to particular queries in CourtListener. This can be done in one of two ways:

1. For normal users, subscribe to a query via the CourtListener website itself.

2. For servers, the best way is to use the Search Alert API.

   For example, this shell code creates a Search Alert for new legal decisions mentioning the Obergefell v. Hodges case:

   curl -X POST \ --url https://www.courtlistener.com/api/rest/v3/alerts/ \ --header 'Authorization: Token <your-token-here>' \ --data 'name=My Obergefell Alert' \ --data 'query=q=Obergefell+v.+Hodges&type=o&order_by=score+desc&stat_Precedential=on&docket_number=14-556' \ --data 'rate=wly'

After you’ve created a Search Alert, we’ll send webhook events to your endpoint each time new results are available for your query.

The Search Alert event is a JSON hash with two keys, webhook and payload. payload has two keys, results that contains the search results and alert for the Search Alert details.

The shape of the data is thus:

{ "payload": { "results": [...], "alert": {...} }, "webhook": {...} }

The results key is based on the Search API endpoint and has all the same fields. Review the Search API documentation for details on how it works; it is slightly different than all of our other API endpoints.

The alert key is based on the Search Alert endpoint and has all the same fields except for the resource_uri field, which is omitted.

To get a description of the Search Alert object, do an HTTP OPTIONS request to the API endpoint:

curl -X OPTIONS \ --url 'https://www.courtlistener.com/api/rest/v3/alerts/' \ --header 'Authorization: Token <your-token-here>' 

Old Docket Alert Events

If a case stops receiving updates due to being terminated or otherwise dormant, we automatically disable any docket alerts that may be configured for it. This helps ease the load on our servers, and helps users in our free tier identify cases that they may wish to stop following.

To help our users manage this, we send a weekly email telling our users about any docket alerts they have that will soon be automatically disabled. This allows them to take one of three actions on the alert:

1. Do nothing — If the user does this, the alert will soon be deleted during the next week's automatic process.

2. Delete the alert — The user will immediately stop getting alerts for the case.

3. Re-up the alert — This tells us that the user wishes to continue getting alerts for the case and pushes out the automatic disablement by about six months.

By subscribing to this webhook your server will get a notification similar to the weekly email we send to users. At that time, your server can decide whether to continue monitoring stagnant cases (by re-upping them; see below) or let the automatic disablement occur.

As with our other events, this webhook event is a JSON hash with two keys, webhook and payload. payload has two keys:

• disabled_alerts (Automatically Disabled Alerts):

  Contains a list of docket alerts that have been automatically disabled by our system on terminated cases that haven’t had updates for over 180 days. You can re-enable these alerts if they were disabled by mistake.

• old_alerts (Old Terminated Cases):

  Contains a list of docket alerts on terminated cases that were last updated about 180 days ago. These alerts will be disabled during the next week's process if you do not re-up them for another six months.

The shape of the data is thus:

{ "payload":{ "old_alerts":[ { "id":1, "date_created":"2022-09-23T19:53:36.903277-07:00", "date_last_hit":null, "secret_key":"ehT7V9rmnBNIOV6rTMmMH0x6EvxeA0nYXfpN3Ks3", "alert_type":1, "docket":1 } ], "disabled_alerts":[...] }, "webhook":{...} }

old_alerts and disabled_alerts contain a list of docket alert objects based on the Docket Alerts API and have all the same fields.

Re-upping a docket alert

If a case has been dormant for a long time, and you wish to continue monitoring it, you must re-up the alert. To do this, send an HTTP PATCH request to the Docket Alerts API:

curl -X PATCH \ --data 'alert_type=1' \ --header 'Authorization: Token <your-token-here>' \ "https://www.courtlistener.com/api/rest/v3/docket-alerts/{id}/" 

Doing the above will tell our system that the alert was recently modified and thus should not be disabled for another six months.

A similar request can be used to disable any docket alert:

curl -X PATCH \ --data 'alert_type=0' \ --header 'Authorization: Token <your-token-here>' \ "https://www.courtlistener.com/api/rest/v3/docket-alerts/{id}/" 

RECAP Fetch Events

The RECAP Fetch API lets you use our servers and infrastructure to purchase items on PACER. Your server simply places a POST request to the API. In response, the API provides an ID for your request and your download is enqueued for processing.

By listening to this webhook endpoint, your server can monitor your requests and take action when they are complete. This avoids the need to poll the API to check when your request has completed.

As with our other events, this webhook event is a JSON hash with two keys, webhook and payload.

The shape of the data is thus:

{ "payload":{...}, "webhook":{...} }

The payload key is based on the RECAP Fetch API endpoint and has all the same fields.

To get a description of the payload object, do an HTTP OPTIONS request to the API endpoint:

curl -X OPTIONS \ --url 'https://www.courtlistener.com/api/rest/v3/recap-fetch/' \ --header 'Authorization: Token <your-token-here>' 

After you set up this endpoint, you will be notified whenever one of your fetch requests terminates in success or failure.

Maintenance Schedule

Major server maintenance is scheduled on Thursday nights from 21:00PT to 23:59PT. If you are scheduling cron jobs or otherwise crawling the API, you may experience downtime during this window.

Bulk processing tasks on our servers can create delays while running. We maintain a public calendar for tracking these tasks.

Change Log

• v1 First release

• v2 - This release introduces support for Case Law Search Alerts results with nested documents.

  You can now select the webhook version when configuring an endpoint. For most webhook event types, there are no differences between v1 and v2, as the payload remains unchanged.

  In the Search Alert webhook event type, the Oral Arguments search response remains identical between v1 and v2.

  For Case Law v2 now includes nested results, which are based on the new changes introduced in v4 of the Search API.