Web hooks

Web hooks provide a method to enhance Fire Arrow's built-in request validation and processing with custom logic. The feature is currently in an early stage and shall be considered as beta. Changes may occur while the feature matures.

Web hooks are executed at defined events. The following events are supported:

• "Post validation, pre request": This web hook is executed after the request has been validated but before it is sent to the FHIR server. The web hook has the ability to continue the request or stop execution.
• "Post request, pre response": This web hook is executed after the request has been sent to the FHIR server. The web hook has the ability to modify the response or stop execution.

Web hook configuration

Web hooks are configured per resource and operation. The following example configures a web hook for the Patient resource and the read operation.

{
  "client_role": "Public",
  "entity_name": "Patient",
  "operation": "read",
  "post_validation_pre_request_hook": "https://my.webhook.site/webhook",
  "validator": "Allowed"
}

Web hook payload

The web hook receives a JSON payload with the following structure:

{
  "client_request": {
    "operation": "read",
    "compartment_name": null,
    "compartment_id": null,
    "entity_name": "Patient",
    "entity_id": "03142a56-f304-4574-aad1-e3ad822c540c",
    "parameters": {}
  },
  "validated_request": {
    "operation": "read",
    "compartment_name": null,
    "compartment_id": null,
    "entity_name": "Patient",
    "entity_id": "03142a56-f304-4574-aad1-e3ad822c540c",
    "parameters": {}
  },
  "client_role": "Public",
  "client_entity_id": null,
  "backend_response": null
}

• client_request: The original request that was sent by the client.
• validated_request: The request as validated by Fire Arrow. This is the request that will be sent to the FHIR server if the web hook does not return an error.
• client_role: The role of the client.
• client_entity_id: The ID of the client entity. (null if the client is not authenticated)
• backend_response: The response from the FHIR server. (only populated for the "post request" web hook)

The web hook can continue or stop the request by returning a JSON object with the following structure:

{
  "proceed": false,
  "error_message": "Observation time can not be changed to an earlier time stamp."
}

• proceed: Whether to proceed with the request.
• error_message: The error message to return to the client.

If the proceed property is set to false, the request will be stopped and the error message will be returned to the client.

The "post request, pre response" web hook can modify the response by returning a JSON object with the following structure:

{
  "proceed": true,
  "backend_response": {
    "resourceType": "Patient",
    "id": "03142a56-f304-4574-aad1-e3ad822c540c",
    "meta": {
      "versionId": "1",
      "lastUpdated": "2025-03-18T12:00:00Z"
    },
    "name": null
  }
}

In this example, the "post request, pre response" web hook modifies the response by setting the name property to null.