Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

1040 Update WH docs #2284

Merged
merged 3 commits into from
Jun 19, 2024
Merged

1040 Update WH docs #2284

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c383685
build: update WH docs
leite08 Jun 15, 2024
def4f9c
fix(docs): typo on WH
leite08 Jun 17, 2024
4baa6ea
build: add wh types to start doc download, consolidated data and bulk…
leite08 Jun 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
build: add wh types to start doc download, consolidated data and bulk… 
… URL

Ref. metriport/metriport-internal#1040

Signed-off-by: Rafael Leite <[email protected]>
  • Loading branch information
@leite08
leite08 committed Jun 18, 2024
commit 4baa6ea57021090063d48a2b27170fc142e4b66f
14 changes: 3 additions & 11 deletions docs/home/api-info/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some thoughts/Qs:

  • Is the "idempotent" requirement essentially just telling the cx that we always expect a 200 HTTP response? Perhaps we should just tell them that, since we don't really care what they do on their end?
  • We've had problems where cx webhook endpoints take a long time to process the payload, and we timeout waiting for the response. Should we instruct them to process the payload async and return us 200 right away?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the "idempotent" requirement essentially just telling the cx that we always expect a 200 HTTP response? Perhaps we should just tell them that, since we don't really care what they do on their end?

No, saying it should be idempotent is not the same thing as saying it should always return 200. They need to design their endpoint in a way that allows it being called multiple times w/ the same payload w/o breaking their app.

We've had problems where cx webhook endpoints take a long time to process the payload, and we timeout waiting for the response. Should we instruct them to process the payload async and return us 200 right away?

Good point, added!

than once with the same payload, with no changes to the end result.
Expand All @@ -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
Expand Down Expand Up @@ -89,16 +89,8 @@ if is_signature_valid:
print("Signature verified")
else:
print("Signature verification failed")


```

<Warning>
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.
</Warning>

### Generating a new webhook key

If using the dashboard: simply delete your webhook URL on the [Developers page](https://dash.metriport.com/developers),
Expand Down
16 changes: 11 additions & 5 deletions docs/medical-api/api-reference/document/download-url-bulk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

<Tip>
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).
</Tip>
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.

<Warning>
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.
Expand Down
13 changes: 8 additions & 5 deletions docs/medical-api/api-reference/document/start-document-query.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

<Tip>
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.
</Tip>
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.

<Warning>
If you were to trigger this endpoint again while the query is still processing, you will get a
Expand Down
9 changes: 7 additions & 2 deletions docs/medical-api/api-reference/fhir/consolidated-data-query-post.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/medical-api/more-info/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Tip>
Note that the webhooks will only contain updates for new data fetched in the current document
Expand Down
Loading