Skip to main content

Webhook for event notifications (Cloud Event)

The eventNotifications method in e-Box Message Registry API 3.5 allows to be notified when partition data changes such as partition creation, modification to routing rules, or updates in partition access rights. This method is also called the webhook and follows the Cloud Event specification.

Instead of consulting the Partition web service for each request from your clients, you must implement the webhook and store the given data in a cache or a temporary database and you have to call the service only for e-Boxes that do not yet have information available on your side. Moreover, the webhook is the only way to be notified about a routing rule update immediately and route messages as soon as the recipient configured it. This is crucial to ensure a message ends up in the expected partition.

As you can see in the Message Registry API, the CloudEvent object contains the property data. The value of the data property is a JSON object following a schema that depends on the event type.

Routing rule events​

There are 3 different event types for routing rules :

  • be.eboxenterprise.v1.routingRule.created
  • be.eboxenterprise.v1.routingRule.updated
  • be.eboxenterprise.v1.routingRule.deleted

All of them follow the same schema :

RoutingRuleEventData:
  description: Data specific to the routing rule event
  type: object
  required: [enterpriseNumber, routingRuleId, orderedRoutingRules]
  properties:
    enterpriseNumber:
     $ref: "#/components/schemas/EnterpriseNumber"
    routingRuleId:
     type: integer
     description: The technical identifier of the added, modified or deleted routing rule. If this is an added or modified routing rule, it can be found in the list of routing rules in the property orderedRoutingRules.
    orderedRoutingRules:
      description: "Partition routing rules on an ebox already ordered from the highest priority to the lowest priority."
      type: "array"
      items:
        description: Partition rule to ease the receipt of this kind of messages
        type: object
        required: [routingRuleId, priority, conditions, targetPartitionId]
        properties:
          routingRuleId:
            type: integer
            description: Routing rule technical identifier
          priority:
            type: integer
            minimum: 1
            description: "The position in the list of routing rules if the list is ordered by priority. The higher is this number, the less priority has the routing rule. For example, if the priority number is 5, this rule must be applied to messages matching the condition instead of the rules that have a higher priority number and with matching condition. There should not be routing rules with the same priority number. If a routing rule is created, the routing rule having the same priority number and all other routing rules having a higher priority number should have their priority number incremented by 1."
          conditions:
            type: array
            items:
              type: object
              description: "Criteria to follow to map a message to a partition. If a property is not given or has a null value, it means that the property can have any value like a wildcard. For example, if condition:{senderApplicationId:myApplication, senderOrganizationId:0123456789} then it means that every new messages from the organization 0123456789 and the sender application myApplication should be moved to the target partition."
              properties:
                messageTypeId:
                  type: string
                  description: identification of the message type
                senderApplicationId:
                  type: string
                  description: identification of the sender application
                senderOrganizationId:
                  $ref: "#/components/schemas/EnterpriseNumber"
          targetPartitionId:
            type: string
            description: the partition where the new messages matching the condition must be moved to.
          creationDate:
            type: string
            description: Date when the user created the routing rule
            format: date-time

The event data contains the rule identifier being created, changed or deleted but the data also contains the resulting routing rule list for the linked e-Box. One of the valid implementation choice is to drop all the stored routing rules on that e-Box and replace them by the rules in the orderedRoutingRules property. The operation cannot be delayed so the new messages are routed to the expected partition as soon as the recipient configure it. In case of error, the Event Notification service performs some retry to ensure that the notification is received.

Here is an example of an eventNotification request about routing rules :

Example​

{
  "specversion": "1.0",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "subject": "0123456789",
  "time": "2025-09-10T10:33:35+02:00",
  "dataschema": "https://dev.eboxenterprise.be/docs/spec/specifications#event-notification",
  "source": "documentmanagement:publication:eboxenterprise:client:public",
  "type": "be.eboxenterprise.v1.routingRule.created",
  "datacontenttype": "application/json",
  "data": {
    "enterpriseNumber": "0123456789",
    "routingRuleId": 1,
    "orderedRoutingRules": [
      {
        "routingRuleId": 1,
        "priority": 1,
        "conditions": [
          {
            "messageTypeId": "TestMessageTypeId",
            "senderApplicationId": "application:to:test:ebox:sender",
            "senderOrganizationId": "0206731645"
          }
        ],
        "targetPartitionId": "HRdepartment",
        "creationDate": "2025-09-10T10:33:35+02:00"
      }
    ]
  }
}

Partition access right event​

There are 2 different event for partition access rights :

  • be.eboxenterprise.v1.userPartitionRights.rightAdded
  • be.eboxenterprise.v1.userPartitionRights.rightRemoved

All of them follow the same schema :

UserPartitionRightsEventData:
  description: data specific to the userPartitionRights event
  type: object
  properties:
    enterpriseNumber:
      $ref: "#/components/schemas/EnterpriseNumber"
    partitionId:
      description: "The partition business identifier"
      type: "string"
      example: "HRdepartment"
    userSsin:
      description: Social Security Identification Number issued by the National Register or CBSS
      type: string
      pattern: '^\d{11}$'
      example: "44022722580"
  required: [enterpriseNumber, partitionId, userSsin]

You can then handle a cache or a database and add or delete the entry {enterpriseNumber, partitionId, userSsin} when you receive an event about user partition right. If you receive a consultation request from a human user on an e-Box that is not yet in your data, you still have to consult the Partition web service. Here is an exemple of an avant about an added user access right on a partition:

Example​

{
  "specversion": "1.0",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "subject": "0534530277",
  "time": "2025-08-29T11:57:23.998Z",
  "dataschema": "https://dev.eboxenterprise.be/docs/spec/specifications#event-notification",
  "source": "documentmanagement:publication:eboxenterprise:client:public",
  "type": "be.eboxenterprise.v1.userPartitionRights.rightAdded",
  "datacontenttype": "application/json",
  "data": {
    "enterpriseNumber": "0206731645",
    "partitionId": "MyTestPartition",
    "userSsin": "44022722580"
  }
}

Partition event​

There are 2 different event types for Partition :

  • be.eboxenterprise.v1.partition.created
  • be.eboxenterprise.v1.partition.deleted

All of them follow the same schema:

PartitionEventData:
  description: "data specific to the Partition event"
  type: object
  properties:
    enterpriseNumber:
      $ref: "#/components/schemas/EnterpriseNumber"
    partitionId:
      description: "The partition business identifier"
      type: "string"
      example: "HRdepartment"
  required: [enterpriseNumber, partitionId]

If you handle a cache or a database about the partition user access rights or the routing rules, in case of a deleted partition event, you must delete the entries about the deleted partition. That is to say you must delete all user access right on that partition in that ebox and all the routing rules that the partitionPartionId is the deleted partition. Here is an example of a notification about a deleted partition:

Example​

{
  "specversion": "1.0",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "subject": "0534530277",
  "time": "2025-08-29T11:57:23.998Z",
  "dataschema": "https://dev.eboxenterprise.be/docs/spec/specifications#event-notification",
  "source": "documentmanagement:publication:eboxenterprise:client:public",
  "type": "be.eboxenterprise.v1.partition.deleted",
  "datacontenttype": "application/json",
  "data": {
    "enterpriseNumber": "0206731645",
    "partitionId": "MyDeletedPartition"
  }
}