diff --git a/docs/home/api-info/webhooks.mdx b/docs/home/api-info/webhooks.mdx
index 67dc20875e..50362b97a1 100644
--- a/docs/home/api-info/webhooks.mdx
+++ b/docs/home/api-info/webhooks.mdx
@@ -29,6 +29,7 @@ General requirements for the endpoint:
1. Does not do an HTTP redirect (redirects will not be followed);
1. Accepts a `POST` HTTP request;
1. Verifies requests using the HTTP header `x-metriport-signature` - see [authentication](#authentication) below;
+1. Responds `200` in under 4 seconds - we recommend processing the webhook request asynchronously;
1. Accepts and responds to a [`ping` message](#the-ping-message);
1. Be [idempotent](https://en.wikipedia.org/wiki/Idempotence) - it should accept being called more
than once with the same payload, with no changes to the end result.
@@ -39,9 +40,8 @@ Additionally, your endpoint will need to accept and process different messages w
## Authentication
-When Metriport sends a webhook message, it includes an `x-metriport-signature` header.
-
-- `x-metriport-signature`: This is an [HMAC](https://en.wikipedia.org/wiki/HMAC) SHA-256 hash computed using your webhook key and the body of the webhook message.
+When Metriport sends a webhook message, it includes an `x-metriport-signature` header - this is an
+[HMAC](https://en.wikipedia.org/wiki/HMAC) SHA-256 hash computed using your webhook key and the body of the webhook message.
At a high level, an HMAC works by taking a secret key (webhook key from the Settings page) and a message,
and performing iterative hashes of the two to create a signature. That signature is compared against the
@@ -89,16 +89,8 @@ if is_signature_valid:
print("Signature verified")
else:
print("Signature verification failed")
-
-
```
-
- The previous method of authenticating webhooks, comparing your webhook key with the
- `x-webhook-key` in each request's HTTP header, is being deprecated on **December 9th, 2023**.
- Please update your implementation to use the `x-metriport-signature` header for authentication.
-
-
### Generating a new webhook key
If using the dashboard: simply delete your webhook URL on the [Developers page](https://dash.metriport.com/developers),
diff --git a/docs/medical-api/api-reference/document/download-url-bulk.mdx b/docs/medical-api/api-reference/document/download-url-bulk.mdx
index 0b2965fc83..782ec3c6eb 100644
--- a/docs/medical-api/api-reference/document/download-url-bulk.mdx
+++ b/docs/medical-api/api-reference/document/download-url-bulk.mdx
@@ -3,13 +3,19 @@ title: "Start Bulk Get Document URL"
description: "Triggers a process to generate a list of download URLs for all of the patient's documents."
api: "POST /medical/v1/document/download-url/bulk"
---
-When executed, this endpoint triggers a process to generate all download URLs for a patient's documents, which will then be delivered via webhook message.
+When executed, this endpoint triggers a process to generate all download URLs for a patient's documents.
+This is an asynchronous process, and the status is returned in the response to the original request.
-The status of the process is returned in the response. Initially, it will be `processing`, and when the process is finished, the status will be updated to `completed` or `failed`.
+Initially, the status will be `processing`, and when the process is finished, the status will be updated to
+`completed` or `failed`.
-
- The result of the process will be delivered via a webhook message - to set this up, and see the message format, check out our [webhooks guide](/medical-api/more-info/webhooks#bulk-downloadable-url-generation).
-
+Once completed, a webhook request will be sent [your configured URL](/home/api-reference/settings/post-settings)
+containing the document download URLs.
+
+Webhook message type - see [the respective section on the webhooks page](/medical-api/more-info/webhooks#bulk-downloadable-url-generation)
+for more details:
+
+- `medical.document-bulk-download`: list of download urls for a patient's documents.
If you trigger this endpoint again while the process is still running, you will get a response that reflects the current progress. Essentially, only a single bulk URL generation process will be running for a patient at any given time.
diff --git a/docs/medical-api/api-reference/document/start-document-query.mdx b/docs/medical-api/api-reference/document/start-document-query.mdx
index a02377befd..535253b2c3 100644
--- a/docs/medical-api/api-reference/document/start-document-query.mdx
+++ b/docs/medical-api/api-reference/document/start-document-query.mdx
@@ -15,11 +15,14 @@ incremented. Once all documents have been converted it too will be marked as `co
If there's no document to be converted, the total will be set to zero and the status to `completed`.
-
- To get updates about the document query progress, including download and conversion status, check
- out our [webhooks guide](/medical-api/more-info/webhooks). Note that the webhooks will only
- contain updates for new data fetched in the current document query.
-
+Once each process completes, a webhook request will be sent to [your configured URL](/home/api-reference/settings/post-settings)
+containing the available data. **Note:** the webhooks will only contain updates for new data fetched in the current document query.
+
+Webhook message types - see [the respective section on the webhooks page](/medical-api/more-info/webhooks#patient-document-data)
+for more details:
+
+- `medical.document-download`: contains the newly downloaded documents for the patient;
+- `medical.document-conversion`: result of converting the newly downloaded C-CDA documents into FHIR.
If you were to trigger this endpoint again while the query is still processing, you will get a
diff --git a/docs/medical-api/api-reference/fhir/consolidated-data-query-post.mdx b/docs/medical-api/api-reference/fhir/consolidated-data-query-post.mdx
index bb0e067113..060c31c4b5 100644
--- a/docs/medical-api/api-reference/fhir/consolidated-data-query-post.mdx
+++ b/docs/medical-api/api-reference/fhir/consolidated-data-query-post.mdx
@@ -7,10 +7,15 @@ api: "POST /medical/v1/patient/{id}/consolidated/query"
When executed, this endpoint triggers an asynchronous query to retrieve a Patient's consolidated
data from the FHIR repository.
-Once the data is consolidated and ready for consumption, a [Webhook request](/medical-api/more-info/webhooks#patient-consolidated-data)
-is sent to [your configured URL](/home/api-reference/settings/post-settings) containing the Patient's
+Once the data is consolidated and ready for consumption, webhook requests will be sent to
+[your configured URL](/home/api-reference/settings/post-settings) containing the Patient's
data in FHIR-compliant format, based on the [parameters](#query-params) used to trigger the query.
+Webhook message type - see [the respective section on the webhooks page](/medical-api/more-info/webhooks#patient-consolidated-data)
+for more details:
+
+- `medical.consolidated-data`: contains the patient's data in FHIR format.
+
You'll be able to query multiple times for the same Patient which will be added to the queue and
processed in order. If the parameters are the same as a previous query that is still processing,
the new query will be ignored and you'll get the status and request ID of the previous one.
diff --git a/docs/medical-api/more-info/webhooks.mdx b/docs/medical-api/more-info/webhooks.mdx
index 57e4436075..9ec0d690ec 100644
--- a/docs/medical-api/more-info/webhooks.mdx
+++ b/docs/medical-api/more-info/webhooks.mdx
@@ -52,8 +52,8 @@ These are messages you can expect to receive in the following scenarios:
you'll be able to [download the raw files](/medical-api/api-reference/document/get-document);
2. Then, if the downloaded documents contained C-CDA/XML files, when the conversion to FHIR has
completed, the message `type` will be `medical.document-conversion`, and at this point
- you'll be able to query for [patient consolidated data](#patient-consolidated-data) in
- FHIR-compliant format.
+ you'll be able to query for [patient consolidated data](/medical-api/api-reference/fhir/consolidated-data-query-post)
+ in FHIR-compliant format.
Note that the webhooks will only contain updates for new data fetched in the current document