Configure your webhooks

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": {
        ...
      }
    }
  ]
}

Events available :

• Patient updated
  This event is triggered when a patient has been updated.
  JSON

  {
    "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.
  JSON

  {
    "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.
  json

  {
    "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 :

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
  JSON

  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.