Integration - Stellar Developer Docs

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

# dev.services.yaml
events:
  enabled: true
  queue:
    type: kafka
    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

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

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 about their users’ transactions and customer information. The schema of the event data will depend on the type of event being sent. To receive events as a client application, you will need to expose callback URLs 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. The schema of the event data will depend on the type of event being sent. Anchor Platform allows unique endpoints to be configured by event type. 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

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

# dev.services.yaml
callback_api:
  base_url: http://localhost:8081/callback
  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_AUTH_TYPE=api_key
CALLBACK_API_AUTH_API_KEY_HTTP_HEADER=X-Api-Key
SECRET_CALLBACK_API_AUTH_SECRET="your API key"

# dev.services.yaml
callback_api:
  base_url: http://localhost:8081/callback
  auth:
    type: api_key
    api_key:
      http_header: X-Api-Key

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.

​Requirements

​Configuration

​Receiving Events

​As a Client Application

​Callback Signing

​As a Business Server

​Configuration

Requirements

Configuration

Receiving Events

As a Client Application

Callback Signing

As a Business Server

Configuration