Configure your webhooks
We use webhooks to notify your applications when specific patient-related events happen.
Create a webhook from the developer portal
You can create webhooks from the developer portal. We will ask you to define:
- the callback URL for the webhook
- an optional name for the webhook (ex: webhook about patient event in all my healthcare structures)
- the events types you want to receive (ex: patient updated, encounter created)
To secure your webhooks, we recommend to use the signature-key
we provide when you create them. Please see the dedicated section for the security best practices.
Webhook endpoints must support at least 10 calls per second in your application. We will send you the notification by batch to avoid to spam your webhook. There might be a few minutes delay (max 2 minutes) between the moment the event is triggered and the moment you receive the notification by batch. This delay cannot be parametered in your portal developer.
Event Format
The JSON object returned contains a list of events. All the events in the list will have the same event-type. Any event is composed by 2 types of data : fixed fields and some details different for each event based on the event type.
Global format :
{
"notification-uuid": "9a703791-f920-4b99-a686-638be8ebbbce",
"events": [
{
"event-uuid": "f71d8c5d-1ea5-4457-885b-88ef8c0a757d",
"webhook-id": "bf17b9bf-e7db-4788-aabb-d71d87b3907c",
"event-type": "encounter.created",
"database-reference": "Vz1HI8X9aS",
"timestamp": "2023-04-13T08:40:42.146Z",
"event-details": {
...
}
}
]
}
Field | Type | Description |
---|---|---|
notification-uuid | uuid | Unique id to identify the notification sent to your webhook |
events | array | List of events for a certain event type |
event-uuid | uuid | Unique id to identify the event (useful to avoid managing the same event twice) |
webhook-id | uuid | Unique id to identify your webhook |
event-type | string | Event type chosen when you subscribe |
database-reference | string | Identifier which represents your application deployed in one healthcare structure |
timestamp | ISO Format + UTC | Date/time of the event triggered in Lifen system |
event-details | object | Content details about an event (different for each event type, see the examples below) |
Events available :
- Patient updated
This event is triggered when a patient has been updated.{ "notification-uuid": "9a703791-f920-4b99-a686-638be8ebbbce", "events": [ { "event-uuid": "f71d8c5d-1ea5-4457-885b-88ef8c0a757d", "webhook-id": "bf17b9bf-e7db-4788-aabb-d71d87b3907c", "event-type": "patient.updated", "database-reference": "Vz1HI8X9aS", "timestamp": "2023-04-13T08:40:42.146Z", "event-details": { "patient-id": "111111", "patient-ipp": "222222" } } ] }
- Patient merged
This event is triggered when a patient has been merged with another one.{ "notification-uuid": "9a703791-f920-4b99-a686-638be8ebbbce", "events": [ { "event-uuid": "f71d8c5d-1ea5-4457-885b-88ef8c0a757d", "webhook-id": "bf17b9bf-e7db-4788-aabb-d71d87b3907c", "event-type": "patient.merged", "database-reference": "Vz1HI8X9aS", "timestamp": "2023-04-13T08:40:42.146Z", "event-details": { "source-patient-id": "111111", "source-patient-ipp": "222222", "target-patient-id": "333333", "target-patient-ipp": "444444" } } ] }
- Encounter created
This event is triggered when an encounter has been created.{ "notification-uuid": "9a703791-f920-4b99-a686-638be8ebbbce", "events": [ { "event-uuid": "f71d8c5d-1ea5-4457-885b-88ef8c0a757d", "webhook-id": "bf17b9bf-e7db-4788-aabb-d71d87b3907c", "event-type": "encounter.created", "database-reference": "Vz1HI8X9aS", "timestamp": "2023-04-13T08:40:42.146Z", "event-details": { "encounter-id": "6666666", "encounter-status": "in-progress", "patient-id": "111111", "functional-units": [] } } ] }
Headers available :
Header | Type | Example |
---|---|---|
x-lifen-platform-signature | string | 9b329e633efebd025273e6b539a59a57ad954c90a8fdea4e8e070430d2de4880 |
x-lifen-platform-database-reference | string | Vz1HI8X9aS |
x-lifen-platform-event-type | string | encounter.created |
Retry rules
When we call your webhook, we expect you to return a 200 response. We require you to send a successful 200 response within 10 seconds. If we don't get a response within 30 seconds, we retry the event. We recommend that you write any long-running processes as code that can run asynchronously outside the webhook endpoint.
If we encounter an error with a message sent to your webhook (ie. http code different than 2xx
or a late response), we will try to resend the message 5 times over 15 minutes. We will try also after one hour if the last try have failed (3 times over 3 hours).
If all retries fails, we will suspend your webhook. We'll send you (to all the developer portal member) an email notification letting you know your webhook has been suspended. You will be able to re-enable your webhook again in your developer portal after fixing the bug.
If you respond with the 429 Too many requests
http status, with Retry-After
header in seconds, Lifen will respect this time.
Test your webhook
Step 1 : Configuration
- Register public endpoint
- in POST mode
- in https
- allowed to received JSON (each event has it’s own format so refer to the Event Format section)
Step 2 : Subscription
- Register subscription in the developer portal and choose the events you want
Step 3 : Test
- Use webhook.site to register test endpoint
- Update the webhook configuration with this test url to verify that the events finally arrived
- Click on the test button in developer portal
Step 4 : Receive a notification
- Verify that the header mentioned for security exists
- signature
- database reference
- event type
- Verify the event format
Exemple : merged patient { "notification-uuid": "9a703791-f920-4b99-a686-638be8ebbbce", "events": [ { "event-uuid": "f71d8c5d-1ea5-4457-885b-88ef8c0a757d", "webhook-id": "bf17b9bf-e7db-4788-aabb-d71d87b3907c", "event-type": "patient.merged", "database-reference": "Vz1HI8X9aS", "timestamp": "2023-04-13T08:40:42.146Z", "event-details": { "source-patient-id": "111111", "source-patient-ipp": "222222", "target-patient-id": "333333", "target-patient-ipp": "444444" } } ] }
- Verify the event status
Step 5 : Verify
- Before responding to the notification, the application must verify that the notification has been sent by Lifen. The application can verify this by calculating the signature of the event.
- Each notification contains a header (
x-lifen-platform-signature
) signed by an API secret key. This key is generated in the dev portal for your application. - The application must decode this header and check its conformity
Step 6 : Respond
- The application must respond with a 2xx OK code to confirm that it has received the notification. Any other code will be considered an error.
Updated over 1 year ago