API Reference
Start typing to search…

Webhooks

Webhooks at b.well

Our webhook service provides real-time notifications about events that happen in our system, enabling your applications to respond immediately to changes and actions. Our system sends HTTP POST requests to the URLs you specify in your webhook settings whenever certain events occur.

Why Use Webhooks?

Webhooks are efficient and simple. Instead of requiring you to poll our API for changes continually, we push information to your endpoint as the events occur. This means you get data immediately and reduce the overhead of making numerous API calls.

Configuring Webhooks

To start receiving webhook events, you need to configure your webhook URLs through your account settings on our platform. Once set up, you will receive POST requests with payloads containing detailed information about the event that triggered the webhook.

Security

Each webhook event is sent over HTTPS to ensure data integrity and security. We recommend verifying the signatures of each webhook to confirm that the requests are coming from our servers.

Events

Currently, we support two types of events -

  1. User-Delete-Completed
  2. Data-Export-Completed

More events may be added in the future based on user feedback and system upgrades.

Understanding Message Definitions

Each webhook event is structured around a specific MessageDefinition that dictates the format and content of the message payload. This ensures consistency and helps developers integrate more efficiently.

Message Definition Explained

  • ResourceType - Identifies the type of FHIR resource.
  • ID - A unique identifier for the message definition.
  • URL - The location where the message definition can be accessed.
  • EventCoding - Contains the system and code that categorizes the type of event.
  • Focus - Specifies the primary resource concerned by the event, such as Person or DocumentReference.

Event Payloads

User-Delete-Completed Event

This event notifies your systems when a user account has been successfully deleted.

Payload Structure

{  
  "resourceType": "MessageHeader",  
  "id": "mh12345",  
  "eventCoding": {  
    "system": "http://icanbwell.com/event-types",  
    "code": "user-delete-completed"  
  },  
  "source": {  
    "endpoint": "<https://icanbwell.com">  
  },  
  "destination": [  
    {  
      "endpoint": "https://client.system.com/webhook"  
    }  
  ],  
  "focus": [  
    {  
      "reference": "Person/789"  
    }  
  ],  
  "extension": [  
    {  
      "url": "http://example.com/fhir/StructureDefinition/external-identifier",  
      "valueIdentifier": {  
        "system": "urn:client:identifier",  
        "value": "client-specific-identifier"  
      }  
    }  
  ]  
}

Fields Explained

  • resourceType, id, eventCoding - Define the type and purpose of the event.
  • source, destination - Indicate where the event originated and where the webhook data is being sent.
  • focus - Points to the resource that triggered the event.
  • extension - Provides additional data such as the external identifier of the deleted user.

Data-Export-Completed Event

This event is triggered when a data export initiated by a user is completed and the data is available for download.

{  
  "resourceType": "MessageHeader",  
  "id": "mh12345",  
  "eventCoding": {  
    "system": "http://icanbwell.com/event-types",  
    "code": "data-export-completed"  
  },  
  "source": {  
    "endpoint": "https://icanbwell.com"  
  },  
  "destination": [  
    {  
      "endpoint": "https://client.system.com/webhook"  
    }  
  ],  
  "focus": [  
    {  
      "reference": "Person/456"  
    }  
  ],  
  "extension": [  
    {  
      "url": "http://example.com/fhir/StructureDefinition/external-identifier",  
      "valueIdentifier": {  
        "system": "urn:client:identifier",  
        "value": "client-specific-identifier"  
      }  
    },  
    {  
      "url": "http://example.com/fhir/StructureDefinition/download-url",  
      "valueUri": "https://icanbwell.com/downloads/data-export-12345.zip"  
    }  
  ]  
}

Fields Explained

  • resourceType, id, eventCoding - Define the type and purpose of the event.
  • source, destination - Indicate where the event originated and where the webhook data is being sent.
  • focus - Points to the Person resource that triggered the event. This focus ensures that the event is directly linked to the person associated with the data export.
  • extension - Provides additional data such as the external identifier of the person involved in the data export and the URL where the exported data can be downloaded.

Summary

Our webhooks provide a robust mechanism for receiving real-time updates about significant events in our system. By integrating with our webhooks, you can enhance the responsiveness and efficiency of your applications.