Receiving Events

Any service available at an accessible URL can be an event handler. Synapse can send events to such services via HTTP requests. The service must be able to handle requests containing events.

Endpoint types

Axon Synapse can send HTTP requests containing events in three different ways. Each endpoint that registers as an event handler must support one of them.

http-raw

Axon Synapse serializes a single event directly into the HTTP request’s body when interacting with http-raw endpoints. It provides all other relevant information in the HTTP headers of the request:

  • Content-Type

  • AxonIQ-MessageId

  • AxonIQ-EventName

  • AxonIQ-DateTime

  • AxonIQ-Index

  • AxonIQ-AggregateId

  • AxonIQ-AggregateType

  • AxonIQ-SequenceNumber

The http-raw type does support sending any binary payload directly. Please refer to the API documentation for detailed information about the HTTP request structure.

http-message

When interacting with http-message endpoints, Axon Synapse generates a JSON message that contains the serialized event and all information related to the event. It then sends that JSON message in the HTTP request’s body.

The http-message type requires you to specify the serializer used if you want to send arbitrary binary payloads. Please refer to the API documentation (select application/json request body schema) for detailed information about the HTTP request structure.

http-list-of-messages

When interacting with http-list-of-messages endpoints, Axon Synapse generates a JSON message that contains a list of events. Each element includes a serialized event and all additional information relevant to the event.

The http-list-of-messages type requires you to specify the serializer used if you want to send arbitrary binary payloads. Please refer to the API documentation (select application/vnd.axoniq.event.list+json request body schema) for detailed information about the HTTP request structure.

Registering event handlers

Event handlers must explicitly register in Axon Synapse to receive events from Axon Server. There are two ways to register an event handler - using Synapse’s Web interface or through the Synapse HTTP API.

In both cases, Axon Synapse needs the following information:

Event names

a list of event type names that this handler can handle (when empty, the handler receives all events)

Client ID

unique ID for the handler application instance

Component name

a logical name for the handler application

HTTP Endpoint

the URL of the handler

Endpoint Type

specifies whether the handler expects a raw or message request type

Endpoint Options

any key/value pairs that Axon Synapse should include in requests to the handler (as HTTP headers)

Batch size

the maximum number of events that Synapse sends in one request to the handler if the endpoint type is http-list-of-messages.

serializer

The serializer used to encode payloads. Currently TEXT and BASE64 are supported.

  • TEXT is the default serializer and tries to serialize the payload as an UTF8 string. All data not reprensentable by UTF8 will be lost.

  • BASE64 will encode your payload as Base64 and put that as a string into the payload field.

Start

the global index of the first event to read from the event store (use 0 to start from the first event, use -1 to start from the last event)

Registering an event handler via Axon Synapse UI

To register an event handler via Axon Synapse UI, go to Event Handlers  Register new event handler and fill in the form:

"Screenshot of the Axon Synapse UI for registering a new event handler

Registering an event handler via Axon Synapse API

To register an event handler via Axon Synapse API, send a JSON request to the respective endpoint. You can find detailed information about the endpoint in the API documentation.

Below is a sample JSON request to register a handler:

POST http://synapse:8080/v1/contexts/default/handlers/events
Content-Type: application/json

{
  "names": [
    "local.application.client.Event"
  ],
  "endpoint": "https://client.application.local/v1/message",
  "endpointType": "http-raw",
  "endpointOptions": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "clientId": "application-name-7c78946494-p86ts",
  "componentName": "application-name",
  "batchSize": 0,
  "start": 0,
  "enabled": true
}