Merge pull request #4878 from freelawproject/4752-document-webhooks-v2

4752 Updated documentation regarding Webhooks v2

cl/api/templates/search-api-docs-vlatest.html

@@ -154,7 +154,7 @@ <h3 id="type">Setting the Result <code>type</code></h3>
     <tbody>
     <tr>
       <td><code>o</code></td>
-      <td>Case law opinions</td>
+      <td>Case law opinion clusters with nested Opinion documents.</td>
     </tr>
     <tr>
       <td><code>r</code></td>

cl/api/templates/webhooks-docs-vlatest.html

@@ -1,6 +1,7 @@
 {% extends "base.html" %}
 {% load static %}
 {% load extras %}
+{% load waffle_tags %}
 
 {% block title %}Webhook API – CourtListener.com{% endblock %}
 {% block description %}
@@ -216,7 +217,7 @@ <h3 id="retries">Retries and Automatic Endpoint Disablement</h3>
   <p>Fixed webhook endpoints can be re-enabled in the webhooks panel.
   </p>
   <p>
-    <img src="{% static "png/re-enable-webhook.png" %}"
+    <img src="{% static "png/re-enable-webhook-v2.png" %}"
        alt="screenshot of how to re-enable a webhook endpoint"
        class="img-responsive img-rounded shadow center-block"
        height="261"
@@ -419,6 +420,13 @@ <h2 id="change-log">Change Log</h2>
       <p><strong>v1</strong> First release
       </p>
     </li>
+    <li>
+      <p><strong>v2</strong> - This release introduces support for Case Law Search Alerts results with nested documents.</p>
+      <p>You can now select the webhook version when configuring an endpoint. For most webhook event types, there are no differences between <code>v1</code> and <code>v2</code>, as the payload remains unchanged.
+      </p>
+      <p>In the Search Alert webhook event type, the Oral Arguments search response remains identical between <code>v1</code> and <code>v2</code>.</p>
+      <p>For Case Law {% flag "recap-alerts-active" %}and RECAP{% endflag %} <code>v2</code> now includes nested results, which are based on the new changes introduced in <code>v4</code> of the <a href="{% url "search_api_help" version="v4" %}">Search API.</a></p>
+    </li>
   </ul>
 </div>
 {% endblock %}

cl/api/templates/webhooks-getting-started.html

@@ -104,7 +104,7 @@ <h2 id="setup-a-webhook">Set Up a Webhook Endpoint in CourtListener</h2>
   <p>To set up a webhook endpoint, begin by logging into CourtListener and going to the <a href="{% url 'view_webhooks' %}">Webhooks panel in your profile</a>:
   </p>
   <p>
-    <img src="{% static "png/webhooks-panel.png" %}"
+    <img src="{% static "png/webhooks-panel-v2.png" %}"
        alt="screenshot of the webhook panel"
        class="img-responsive img-rounded shadow center-block"
        height="261"
@@ -114,7 +114,7 @@ <h2 id="setup-a-webhook">Set Up a Webhook Endpoint in CourtListener</h2>
   <p class="v-offset-above-2">Click the “Add webhook” button and the “Add webhook endpoint” modal pops up:
   </p>
   <p>
-    <img src="{% static "png/add-webhook-endpoint.png" %}"
+    <img src="{% static "png/add-webhook-endpoint-v2.png" %}"
        alt="screenshot of how to add a webhook endpoint"
        class="img-responsive img-rounded shadow center-block"
        height="261"
@@ -129,7 +129,11 @@ <h2 id="setup-a-webhook">Set Up a Webhook Endpoint in CourtListener</h2>
     </li>
     <li>
       <p>Select the Event Type for which you wish to receive events.</p>
-      <p>You can only create one Webhook endpoint for each type of event. Please get in touch if this limitation causes difficulty for your application.
+    </li>
+    <li>
+      <p>Choose the webhook version you wish to set up.</p>
+      <p>We recommend selecting the highest available version for your webhook. Refer to the <a href="{% url "webhooks_docs" version="v2" %}#change-log">Change Log</a> for more details on webhook versions.</p>
+      <p>You can only create one Webhook endpoint for each type of event and version. Please get in touch if this limitation causes difficulty for your application.
       </p>
     </li>
     <li>
@@ -141,7 +145,7 @@ <h2 id="setup-a-webhook">Set Up a Webhook Endpoint in CourtListener</h2>
   <p>Click “Create webhook”</p>
   <p>Your Webhook endpoint is now created:</p>
   <p>
-    <img src="{% static "png/webhook-disabled.png" %}"
+    <img src="{% static "png/webhook-disabled-v2.png" %}"
        alt="screenshot of a disabled webhook endpoint"
        class="img-responsive img-rounded shadow center-block"
        height="261"
@@ -152,7 +156,7 @@ <h2 id="testing">Testing a Webhook endpoint.</h2>
   <p>Getting a webhook working properly can be difficult, so we have a testing tool that will send you a sample webhook event on demand. </p>
   <p>To use the tool, go to webhooks panel and click the “Test” button for the endpoint you wish to test:</p>
   <p>
-    <img src="{% static "png/webhook-disabled.png" %}"
+    <img src="{% static "png/webhook-disabled-v2.png" %}"
        alt="screenshot of a disabled webhook endpoint"
        class="img-responsive img-rounded shadow center-block"
        height="261"
@@ -164,7 +168,7 @@ <h2 id="testing">Testing a Webhook endpoint.</h2>
       <p><strong>In the “As JSON” tab</strong>, you can ask our server to send a test event to your endpoint. When you click “Send Webhook Test Event” a new event is created with the information shown and is sent to your endpoint. Test events are not retried, but can be seen in the “Test Logs” tab.
       </p>
       <p>
-        <img src="{% static "png/test-json-webhook-event.png" %}"
+        <img src="{% static "png/test-json-webhook-event-v2.png" %}"
            alt="screenshot of the webhook json test modal"
            class="img-responsive img-rounded shadow center-block"
            height="261"
@@ -174,7 +178,7 @@ <h2 id="testing">Testing a Webhook endpoint.</h2>
     <li>
       <p><strong>In the “As cURL”</strong> tab, you can copy/paste a curl command that can be used to send a test event to your local dev environment.</p>
       <p>
-        <img src="{% static "png/test-curl-webhook-event.png" %}"
+        <img src="{% static "png/test-curl-webhook-event-v2.png" %}"
            alt="screenshot of the webhook curl test modal"
            class="img-responsive img-rounded shadow center-block"
            height="261"

cl/users/api_views.py

@@ -136,14 +136,26 @@ def test_webhook(self, request, *args, **kwargs):
                     {"endpoint_url": webhook.url, "webhook_version": version}
                 ).strip()
             case WebhookEventType.SEARCH_ALERT:
-                event_template = loader.get_template(
-                    "includes/search_alert_webhook_dummy.txt"
+                event_template = (
+                    loader.get_template(
+                        "includes/search_alert_webhook_dummy.txt"
+                    )
+                    if version == WebhookVersions.v1
+                    else loader.get_template(
+                        "includes/search_alert_webhook_dummy_v2.txt"
+                    )
                 )
                 event_dummy_content = event_template.render(
                     {"webhook_version": version}
                 ).strip()
-                event_curl_template = loader.get_template(
-                    "includes/search_alert_webhook_dummy_curl.txt"
+                event_curl_template = (
+                    loader.get_template(
+                        "includes/search_alert_webhook_dummy_curl.txt"
+                    )
+                    if version == WebhookVersions.v1
+                    else loader.get_template(
+                        "includes/search_alert_webhook_dummy_curl_v2.txt"
+                    )
                 )
                 event_dummy_curl = event_curl_template.render(
                     {"endpoint_url": webhook.url, "webhook_version": version}

cl/users/templates/includes/search_alert_webhook_dummy_curl_v2.txt

@@ -0,0 +1,98 @@
+curl --request POST \
+  --url '{{ endpoint_url }}' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: 59f1be59-e428-427a-a346-9cacded5c1d4' \
+  --data '{
+   "payload":{
+      "results":[
+         {
+            "meta":{
+               "timestamp":"2024-11-15T00:22:15.765337Z",
+               "date_created":"2024-11-15T00:22:15.765337Z"
+            },
+            "court":"Supreme Court of the United States",
+            "judge":"",
+            "source":"C",
+            "status":"Published",
+            "posture":"",
+            "scdb_id":"",
+            "attorney":"",
+            "caseName":"Obergefell v. Hodges",
+            "citation":[
+               "192 L. Ed. 2d 609",
+               "135 S. Ct. 2584",
+               "2015 U.S. LEXIS 4250",
+               "576 U.S. 644"
+            ],
+            "court_id":"scotus",
+            "opinions":[
+               {
+                  "id":2812209,
+                  "meta":{
+                     "timestamp":"2024-11-15T00:22:15.765337Z",
+                     "date_created":"2024-11-15T00:22:15.765337Z"
+                  },
+                  "sha1":"d7bcc865b883abd70d74d9af7578d256ae62a973",
+                  "type":"combined-opinion",
+                  "cites":[
+                     13
+                  ],
+                  "snippet":"Lorem dolor <strong>Obergefell</strong> sit amet, consectetur adipiscing elit.",
+                  "author_id":17,
+                  "local_path":"test/search/opinion_html.html",
+                  "per_curiam":false,
+                  "download_url":"http://www.supremecourt.gov/opinions/14pdf/14-556_3204.pdf",
+                  "joined_by_ids":[
+
+                  ]
+               }
+            ],
+            "syllabus":"",
+            "citeCount":432,
+            "dateFiled":"2015-06-26",
+            "docket_id":2668808,
+            "lexisCite":"2015 U.S. LEXIS 4250",
+            "panel_ids":[
+
+            ],
+            "cluster_id":2812209,
+            "dateArgued":null,
+            "suitNature":"",
+            "neutralCite":"10 Neutral 4",
+            "panel_names":[
+               "Kristine Pena Mendez Jr."
+            ],
+            "sibling_ids":[
+               2812209
+            ],
+            "absolute_url":"/opinion/2812209/obergefell-v-hodges/",
+            "caseNameFull":"Todd Ballard, Julie Smith, Jeanne Peters, Ashley Jordan, and Andrew Thompson v. Johnson LLC, Walker-Bernard, Jones PLC, Bailey Group, and Lopez-Gonzales",
+            "dateReargued":null,
+            "docketNumber":"14-556",
+            "procedural_history":"",
+            "dateReargumentDenied":null,
+            "court_citation_string":"SCOTUS",
+            "non_participating_judge_ids":[
+
+            ]
+         }
+      ],
+      "alert":{
+         "id":1,
+         "name":"Obergefell v. Hodges",
+         "rate":"dly",
+         "user":1,
+         "query":"?q=Obergefell+v.+Hodges&type=o&order_by=score+desc&stat_Precedential=on&filed_after=06%2F01%2F2015&docket_number=14-556&",
+         "secret_key":"MV8yfOSXQvDQauQOCEg0orkgi4hBC4r9yg5Wk3ue",
+         "date_created":"2022-12-02T15:42:34.921805-08:00",
+         "date_last_hit":"2022-12-02T15:42:35.915737-08:00",
+         "date_modified":"2022-12-02T15:42:35.915880-08:00"
+      }
+   },
+   "webhook":{
+      "version":{{ webhook_version }},
+      "event_type":2,
+      "date_created":"2022-12-02T23:42:34.894411+00:00",
+      "deprecation_date":"None"
+   }
+}'

cl/users/templates/includes/search_alert_webhook_dummy_v2.txt

@@ -0,0 +1,94 @@
+{
+   "payload":{
+      "results":[
+         {
+            "meta":{
+               "timestamp":"2024-11-15T00:22:15.765337Z",
+               "date_created":"2024-11-15T00:22:15.765337Z"
+            },
+            "court":"Supreme Court of the United States",
+            "judge":"",
+            "source":"C",
+            "status":"Published",
+            "posture":"",
+            "scdb_id":"",
+            "attorney":"",
+            "caseName":"Obergefell v. Hodges",
+            "citation":[
+               "192 L. Ed. 2d 609",
+               "135 S. Ct. 2584",
+               "2015 U.S. LEXIS 4250",
+               "576 U.S. 644"
+            ],
+            "court_id":"scotus",
+            "opinions":[
+               {
+                  "id":2812209,
+                  "meta":{
+                     "timestamp":"2024-11-15T00:22:15.765337Z",
+                     "date_created":"2024-11-15T00:22:15.765337Z"
+                  },
+                  "sha1":"d7bcc865b883abd70d74d9af7578d256ae62a973",
+                  "type":"combined-opinion",
+                  "cites":[
+                     13
+                  ],
+                  "snippet":"Lorem dolor <strong>Obergefell</strong> sit amet, consectetur adipiscing elit.",
+                  "author_id":17,
+                  "local_path":"test/search/opinion_html.html",
+                  "per_curiam":false,
+                  "download_url":"http://www.supremecourt.gov/opinions/14pdf/14-556_3204.pdf",
+                  "joined_by_ids":[
+
+                  ]
+               }
+            ],
+            "syllabus":"",
+            "citeCount":432,
+            "dateFiled":"2015-06-26",
+            "docket_id":2668808,
+            "lexisCite":"2015 U.S. LEXIS 4250",
+            "panel_ids":[
+
+            ],
+            "cluster_id":2812209,
+            "dateArgued":null,
+            "suitNature":"",
+            "neutralCite":"10 Neutral 4",
+            "panel_names":[
+               "Kristine Pena Mendez Jr."
+            ],
+            "sibling_ids":[
+               2812209
+            ],
+            "absolute_url":"/opinion/2812209/obergefell-v-hodges/",
+            "caseNameFull":"Todd Ballard, Julie Smith, Jeanne Peters, Ashley Jordan, and Andrew Thompson v. Johnson LLC, Walker-Bernard, Jones PLC, Bailey Group, and Lopez-Gonzales",
+            "dateReargued":null,
+            "docketNumber":"14-556",
+            "procedural_history":"",
+            "dateReargumentDenied":null,
+            "court_citation_string":"SCOTUS",
+            "non_participating_judge_ids":[
+
+            ]
+         }
+      ],
+      "alert":{
+         "id":1,
+         "name":"Obergefell v. Hodges",
+         "rate":"dly",
+         "user":1,
+         "query":"?q=Obergefell+v.+Hodges&type=o&order_by=score+desc&stat_Precedential=on&filed_after=06%2F01%2F2015&docket_number=14-556&",
+         "secret_key":"MV8yfOSXQvDQauQOCEg0orkgi4hBC4r9yg5Wk3ue",
+         "date_created":"2022-12-02T15:42:34.921805-08:00",
+         "date_last_hit":"2022-12-02T15:42:35.915737-08:00",
+         "date_modified":"2022-12-02T15:42:35.915880-08:00"
+      }
+   },
+   "webhook":{
+      "version":{{"webhook_version"}},
+      "event_type":2,
+      "date_created":"2022-12-02T23:42:34.894411+00:00",
+      "deprecation_date":"None"
+   }
+}