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 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

OR

# dev.services.yaml
event_processor:
  client_status_callback:
    enabled: true
  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.

Next, 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 an example of how to configure the event service's Kafka producer:

# dev.env
EVENT_QUEUE_TYPE=kafka
EVENT_QUEUE_KAFKA_BOOTSTRAP_SERVER=localhost:29092,localhost:29093
EVENT_QUEUE_KAFKA_CLIENT_ID=ap-event-service
EVENT_QUEUE_KAFKA_RETRIES=0
EVENT_QUEUE_KAFKA_LINGER_MS=1000
EVENT_QUEUE_KAFKA_BATCH_SIZE=10
EVENT_QUEUE_KAFKA_POLL_TIMEOUT_SECONDS=10

OR

# dev.services.yaml
event:
  enabled: true
  queue:
    type: kafka
    kafka:
      bootstrap_server: localhost:29092,localhost:29093
      client_id: ap-event-service
      retries: 0
      linger_ms: 1000
      batch_size: 10
      poll_timeout_seconds: 10

Anchor Platform allows a subset of the Kafka producer's client configuration to be set. The following are the supported configuration options:

  • bootstrap_server: A comma-separated list of Kafka brokers in the format host:port. This corresponds to the Kafka producer's bootstrap.servers configuration.
  • client_id: The client ID to be used by the Kafka producer. This corresponds to the Kafka producer's client.id configuration.
  • retries: The number of times the Kafka producer will retry sending a message. This corresponds to the Kafka producer's retries configuration.
  • linger_ms: The time in milliseconds the Kafka producer will wait before sending a batch of messages. This corresponds to the Kafka producer's linger.ms configuration.
  • batch_size: The maximum number of messages the Kafka producer will send in a single batch. This corresponds to the Kafka producer's batch.size configuration.

For more information on the Kafka producer's client configuration, see the Kafka documentation.

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. The following is an example of how to configure the event service's callback API with JWT authentication:

# dev.env
CALLBACK_API_BASE_URL=http://localhost:8081/callback
CALLBACK_API_SECRET=my-secret
CALLBACK_API_AUTH_TYPE=jwt
CALLBACK_API_JWT_EXPIRATION_MILLISECONDS=30000
CALLBACK_API_JWT_HTTP_HEADER=Authorization

OR

# dev.services.yaml
callback_api:
  base_url: http://localhost:8081/callback
  secret: my-secret
  auth:
  type: jwt
  jwt:
    expiration_milliseconds: 30000
    http_header: Authorization

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_SECRET=my-secret
CALLBACK_API_AUTH_TYPE=api_key
CALLBACK_API_API_KEY_HTTP_HEADER=X-Api-Key

OR

# dev.services.yaml
callback_api:
  base_url: http://localhost:8081/callback
  secret: bf7c2c5b-5c76-4974-a318-ac9c4a2b8514
  auth:
  type: api_key
  jwt:
    http_header: X-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.