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

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.

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.

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.

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
}