Skip to main content

Integration

This guide will walk you through integrating with the event service to start receiving events. The event service currently only supports Apache Kafka as the backend message broker.

It assumes familiarity with Kafka and will not cover how to set up a Kafka cluster.

Requirements​

Anchor Platform will send events to the TRANSACTION Kafka topic. The event service will consume events from this topic and send them to the appropriate endpoints.

Configuration​

First, the event service's Kafka producer need to be configured using the event.queue section of the configuration file or setting the environment variables. The following is the set of required environment variables needed to configure the event service's Kafka producer:

# dev.env
EVENTS_ENABLED=true
EVENTS_QUEUE_TYPE=kafka
EVENTS_QUEUE_KAFKA_BOOTSTRAP_SERVER=localhost:9092

Anchor Platform allows a subset of the Kafka producer's client configuration to be set. See the default values file for more information what is available. For more information on the Kafka producer's client configuration, see the Kafka documentation.

Next, the event processor needs to be configured in the event_processor section of the Anchor Platform Configuration file or setting the environment variables.

# dev.env
EVENT_PROCESSOR_CLIENT_STATUS_CALLBACK_ENABLED=true
EVENT_PROCESSOR_CALLBACK_API_REQUEST_ENABLED=true

This will enable the event processor to start processing events from TRANSACTION topic. In this example, the event processor will send events to client and business server callback endpoints.

Receiving Events​

The event service can be used to send events to client and business server callback endpoints. The event service will send events to these endpoints as HTTP POST requests with the event data in the request body.

As a Client Application​

Client applications can receive updates whenever the status of a SEP transaction changes.

To receive events as a client application, you will need to expose a callback URL that the event service can send events to. The event service will send a POST request to this endpoint with the event data in the request body.

Anchor Platform will only send events to clients listed in the client configuration. See the client configuration documentation for more information.

Callback Signing​

Anchor Platform signs the callback requests it sends to client applications. The signature is included in the Signature header of the request. The callback URL signature specification can be found in the corresponding SEP protocol specifications.

As a Business Server​

In addition to SEP transaction status updates, business servers can receive events about SEP-31 quote creation or SEP-12 customer information updates. The schema of the event data will depend on the type of event being sent. Visit the Event API documentation for more information about the schema of the event data.

To receive events as a business server, you will need to expose a callback URL that the event service can send events to. The event service will send a POST request to this endpoint with the event data in the request body.

Configuration​

The event service's callback API can be configured using the callback_api section of the Anchor Platform configuration file or setting the environment variables.

caution

The --event-processor will ignore any path segments specified in callback_api.base_url and will instead send events to [scheme]://[host]:[port]/event. This is a bug, but in order not to disrupt those using the event processor, we will defer the fix of including path segments in version 3 of the Anchor Platform.

The following is an example of how to configure the event service's callback API with JWT authentication:

# dev.env

# note `/callback` will not be used for event callbacks
# instead events will be sent to `http://localhost:8081/event`
# all other callbacks (rates, customer, etc.) will use the provided `/callback` root path
CALLBACK_API_BASE_URL=http://localhost:8081/callback
CALLBACK_API_AUTH_TYPE=jwt
CALLBACK_API_AUTH_JWT_EXPIRATION_MILLISECONDS=30000
CALLBACK_API_AUTH_JWT_HTTP_HEADER=Authorization
SECRET_CALLBACK_API_AUTH_SECRET="a secret for signing jwts"

The following is an example of how to configure the event service's callback API with API key authentication:

# dev.env
CALLBACK_API_BASE_URL=http://localhost:8081/callback
CALLBACK_API_AUTH_TYPE=api_key
CALLBACK_API_AUTH_API_KEY_HTTP_HEADER=X-Api-Key
SECRET_CALLBACK_API_AUTH_SECRET="your API key"
caution

The http_header is not configurable as of version 2.5.2 and earlier. The default value is Authorization for JWT and X-Api-Key for API key.

Tracking issue: https://github.com/stellar/java-stellar-anchor-sdk/issues/1272

This configures the event service's callback API that will be used to send events to client and business server callback endpoints. The following are the supported configuration options:

  • base_url: The base URL of the business server's callback endpoint.
  • secret: The secret to be used when sending events to the business server's callback endpoint. This is used to sign the request body when JWT authentication is enabled and it is the API key when API key authentication is enabled.
  • auth: The authentication method to be used when sending events to the business server's callback endpoint. The following are the supported authentication methods:
    • JWT: The event service will send a JSON Web Token (JWT) in the Authorization header of the request. The following are the supported configuration options:
      • expiration_milliseconds: The expiration time of the JWT in milliseconds.
      • http_header: The header in which the JWT will be sent.
    • API_KEY: The event service will send an API key in the Authorization header of the request. The following are the supported configuration options:
      • http_header: The header in which the API key will be sent.