HTTP Sink

About 2 min

Overview

The HTTP sink allows for integration between EventStoreDB and external APIs over HTTP or HTTPS. This connector consumes events from an EventStoreDB stream and converts each event's data into JSON format before sending it in the request body to a specified Url. Events are sent individually as they are consumed from the stream, without batching. The event data is transmitted as the request body, and metadata can be included as HTTP headers. The connector also supports Basic Authentication and Bearer Token Authentication. See Authentication.

Quickstart

You can create the HTTP Sink connector as follows:

Powershell

$JSON = @"
{
  "settings": {
    "instanceTypeName": "http-sink",
    "url": "https://api.example.com/",
    "subscription:filter:scope": "stream",
    "subscription:filter:filterType": "streamId",
    "subscription:filter:expression": "example-stream"
  }
}
"@ `

curl.exe -X POST `
  -H "Content-Type: application/json" `
  -d $JSON `
  http://localhost:2113/connectors/http-sink-connector

Bash

JSON='{
  "settings": {
    "instanceTypeName": "http-sink",
    "url": "https://api.example.com/",
    "subscription:filter:scope": "stream",
    "subscription:filter:filterType": "streamId",
    "subscription:filter:expression": "example-stream"
  }
}'

curl -X POST \
  -H "Content-Type: application/json" \
  -d "$JSON" \
  http://localhost:2113/connectors/http-sink-connector

After creating and starting the HTTP sink connector, every time an event is appended to the example-stream, the HTTP sink connector will send the record to the specified URL. You can find a list of available management API endpoints in the API Reference.

Settings

Adjust these settings to specify the behavior and interaction of your HTTP sink connector with EventStoreDB, ensuring it operates according to your requirements and preferences.

Tips

The HTTP sink inherits a set of common settings that are used to configure the connector. The settings can be found in the Sink Options page.

HTTP settings

Name	Details
`url`	required Type: string Description: The URL or endpoint to which the request or message will be sent. See Template Parameters for advanced settings. Default: `""`
`method`	Type: string Description: The method or operation to use for the request or message. Default: `"POST"`
`defaultHeaders`	Type: string Description: Headers included in all messages. Default: `Accept-Encoding:*`
`pooledConnectionLifetime`	Type: TimeSpan Description: Maximum time a connection can stay in the pool before it is no longer reusable. Default: `00:05:00` (5 minutes)

Authentication

The HTTP sink connector supports both Basic and Bearer authentication methods.

Name	Details
`authentication:method`	Type: string Description: The authentication method to use. Default: `None` Accepted Values: `None`,`Basic`,`Bearer`

Basic Authentication

Name	Details
`authentication:basic:username`	Type: string Description: The username for basic authentication. Default: `""`
`authentication:basic:password`	Type: string Description: The password for basic authentication. Default: `""`

Bearer Authentication

Name	Details
`authentication:bearer:token`	Type: string Description: The token for bearer authentication. Default: `""`

Template parameters

The HTTP sink supports the use of template parameters in the URL, allowing for dynamic construction of the request URL based on event data. This feature enables you to customize the destination URL for each event, making it easier to integrate with APIs that require specific URL structures.

The following template parameters are available for use in the URL:

Parameter	Description
`{schema-subject}`	The event's schema subject, converted to lowercase with hyphens
`{event-type}`	Alias for `{schema-subject}`
`{stream}`	The EventStoreDB stream ID

Usage

To use template parameters, include them in the Url option of your HTTP sink configuration. The parameters will be replaced with their corresponding values for each event.

Example:

https://api.example.com/{schema-subject}

For an event with schema subject "TestEvent", this would result in the URL:

https://api.example.com/TestEvent