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
and fill in the form: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
}