Webhook AidboxTopicDestination

This page describes an AidboxTopicDestination, which allows sending events described by an AidboxSubscriptionTopic to a specific HTTP endpoint.

The webhook AidboxTopicDestination works in the following way:

• Aidbox stores events in the database within the same transaction as the CRUD operation.

• After the CRUD operation, Aidbox collects unsent messages (refer to the maxEventNumberInBatch parameter) from the database and sends them to the specified endpoint via a POST request.

• If an error occurs during sending, Aidbox will continue retrying until the message is successfully delivered.

Aidbox topic-based subscriptions

Configuration

To use Webhook with AidboxSubscriptionTopic you have to create AidboxTopicDestination resource.

You need to specify the following profile:

http://aidbox.app/StructureDefinition/aidboxtopicdestination-webhook-at-least-once

Available Parameters

Parameter name	Value type	Description
endpoint *	valueUrl	Webhook URL.
timeout	valueUnsignedInt	Timeout in seconds to attempt notification delivery (default: 30).
keepAlive	valueInteger	The time in seconds that the host will allow an idle connection to remain open before it is closed (default: 120, -1 - disable).
maxMessagesInBatch	valueUnsignedInt	Maximum number of events that can be combined in a single notification (default: 20).
header	valueString	HTTP header for webhook request in the following format: <Name>: <Value>. Zero or many.

* required parameter.

Examples

POST /fhir/AidboxTopicDestination
content-type: application/json
accept: application/json

{
  "resourceType": "AidboxTopicDestination",
  "meta": {
    "profile": [
      "http://aidbox.app/StructureDefinition/aidboxtopicdestination-webhook-at-least-once"
    ]
  },
  "kind": "webhook-at-least-once",
  "id": "webhook-destination",
  "topic": "http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic",
  "parameter": [
    {
      "name": "endpoint",
      "valueUrl": "https://aidbox.requestcatcher.com/test"
    },
    {
      "name": "timeout",
      "valueUnsignedInt": 30
    },
    {
      "name": "maxMessagesInBatch",
      "valueUnsignedInt": 20
    },
    {
      "name": "header",
      "valueString": "User-Agent: Aidbox Server"
    }
  ]
}

Status Introspection

Aidbox provides $status operation which provides short status information of the integration status:

Request

GET /fhir/AidboxTopicDestination/<topic-destination-id>/$status
content-type: application/json
accept: application/json

Response

200 OK

{
 "resourceType": "Parameters",
 "parameter": [
  {
   "valueDecimal": 2,
   "name": "messageBatchesDelivered"
  },
  {
   "valueDecimal": 0,
   "name": "messageBatchesDeliveryAttempts"
  },
  {
   "valueDecimal": 2,
   "name": "messagesDelivered"
  },
  {
   "valueDecimal": 0,
   "name": "messagesDeliveryAttempts"
  },
  {
   "valueDecimal": 0,
   "name": "messagesInProcess"
  },
  {
   "valueDecimal": 0,
   "name": "messagesQueued"
  },
  {
   "valueDateTime": "2024-10-03T07:23:00Z",
   "name": "startTimestamp"
  },
  {
   "valueString": "active",
   "name": "status"
  },
  {
   "name": "lastErrorDetail",
   "part": [
    {
     "valueString": "Connection refused",
     "name": "message"
    },
    {
     "valueDateTime": "2024-10-03T08:44:09Z",
     "name": "timestamp"
    }
   ]
  }
 ]
}

Response format:

Property	Type	Description
messageBatchesDelivered	valueDecimal	Total number of batches that have been successfully delivered.
messageBatchesDeliveryAttempts	valueDecimal	Number of batch delivery attempts that failed. It represents the overall failed delivery attempts.
messagesDelivered	valueDecimal	Total number of events that have been successfully delivered.
messagesDeliveryAttempts	valueDecimal	Number of delivery attempts that failed. It represents the overall failed delivery attempts.
messagesInProcess	valueDecimal	Current number of events in the buffer being processed for delivery.
messagesQueued	valueDecimal	Number of events pending in the queue for send.
startTimestamp	valueDateTime	AidboxTopicDestination start time in UTC.
status	valueString	AidboxTopicDestination status is always active, which means that AidboxTopicDestination will try to send all received notifications.
lastErrorDetail	part	Information about errors of the latest failed attempt to send an event. This parameter can be repeated up to 5 times. Includes the following parameters.
lastErrorDetail .message	valueString	Error message of the given error.
lastErrorDetail .timestamp	valueDateTime	Timestamp of the given error.