# HTTP Sink

<ConnectorLogo name="http" alt="HTTP" />

The HTTP sink posts records from a KurrentDB stream to an external API over
HTTP or HTTPS. The connector converts each record's data to JSON and sends it
as the request body to the URL you specify. It sends records individually as it
consumes them from the stream, without batching. Record metadata can travel as
HTTP headers. The connector also supports Basic Authentication and Bearer Token
Authentication. See [Authentication](#authentication).

## Prerequisites

Before using the HTTP sink connector, ensure you have:

- A data protection token configured in your KurrentDB instance (required to encrypt sensitive fields like passwords and bearer tokens)
- A target HTTP/HTTPS endpoint that can receive POST requests
- Appropriate authentication credentials if the endpoint requires authentication

:::tip
See the [Data Protection](/kurrent-surge/client/connectors/data-protection/) documentation for instructions on configuring the encryption token.
:::

## Quickstart

Create the HTTP sink with `client.Connectors`. Replace `example-http` with your own
connector id:

```csharp
Dictionary<string, string> settings = new() {
    ["instanceTypeName"]               = "http-sink",
    ["url"]                            = "https://api.example.com/",
    ["subscription:filter:scope"]      = "stream",
    ["subscription:filter:filterType"] = "streamId",
    ["subscription:filter:expression"] = "example-stream"
};

await client.Connectors.Create("example-http", settings);
await client.Connectors.Start("example-http");
```

Once started, the connector posts each record appended to `example-stream` to the URL.
[Managing Connectors](/kurrent-surge/client/connectors/manage/) covers the rest of the lifecycle.

## Settings

Adjust these settings to control how the HTTP sink connector behaves and how it interacts with KurrentDB.

:::tip
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](/kurrent-surge/client/connectors/sinks/#settings) page.
:::

| Name                       | Details                                                                                                                                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `url`                      | _required_<br/><br/> **Description:**<br/>The URL or endpoint that the request or message is sent to. See [Template Parameters](#template-parameters) for advanced settings.<br/><br/>**Default**: `""` |
| `method`                   | **Description:**<br/>The method or operation to use for the request or message.<br/><br/>**Default**: `"POST"`                                                                                                  |
| `defaultHeaders`           | **Description:**<br/>Custom headers to include in the request. See [Specifying Custom Headers](#specifying-custom-headers).<br/><br/>**Default**: `"Accept-Encoding:*"`                                         |
| `pooledConnectionLifetime` | **Description:**<br/>Maximum time a connection can stay in the pool before it is no longer reusable.<br/><br/>**Default**: `"00:05:00"` (5 minutes)                                                             |

### Authentication

The HTTP sink connector supports both [Basic](https://datatracker.ietf.org/doc/html/rfc7617) and [Bearer](https://datatracker.ietf.org/doc/html/rfc6750) authentication methods.

| Name                    | Details                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `authentication:method` | **Description:**<br/>The authentication method to use.<br/><br/>**Default**: `"None"`<br/><br/>**Accepted Values:** `"None"`,`"Basic"`, or `"Bearer"` |

#### Basic authentication

| Name                            | Details                                                                             |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| `authentication:basic:username` | **Description:**<br/>The username for basic authentication.<br/><br/>**Default**: `""` |
| `authentication:basic:password` | **Description:**<br/>The password for basic authentication.<br/><br/>**Default**: `""` |

#### Bearer authentication

| Name                          | Details                                                                           |
| ----------------------------- | --------------------------------------------------------------------------------- |
| `authentication:bearer:token` | **Description:**<br/>The token for bearer authentication.<br/><br/>**Default**: `""` |

### Resilience

The HTTP sink uses the shared
[resilience settings](/kurrent-surge/client/connectors/sinks/#resilience-settings), including
`resilience:enabled` and the three delay bounds. It adds these keys on top of them.

| Name                             | Details                                                                                                                                                                                                                     |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resilience:requestTimeoutMs`    | **Description:**<br/>The timeout in milliseconds for a single HTTP request.<br/><br/>**Default**: `"3000"`                                                                                                                     |
| `resilience:maxRetries`          | **Description:**<br/>The maximum number of retry attempts. `"-1"` means retry without a limit.<br/><br/>**Default**: `"-1"`                                                                                                    |
| `resilience:transientErrorDelay` | **Description:**<br/>The delay before retrying a transient error.<br/><br/>**Default**: `"00:00:00"`                                                                                                                            |
| `resilience:retryOnHttpCodes`    | **Description:**<br/>A comma-separated list of status codes to retry on. A code can be exact, such as `408`, or a wildcard for a class, such as `5xx`. Empty means retry on any non-2xx code.<br/><br/>**Default**: `""`         |

## Headers

Besides the [default headers](/kurrent-surge/client/connectors/sinks/#headers) included with every request, the HTTP sink connector adds the following headers to the HTTP request:

| Header              | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `esdb-request-id`   | A unique identifier for the request                            |
| `esdb-request-date` | The timestamp when the request was processed                   |
| `content-type`      | The media type of the resource                                 |
| `accept-encoding`   | The encoding types the client can handle. Default value is `*` |

### Specifying custom headers

The HTTP sink connector lets you include custom headers in the HTTP requests it
sends to your specified URL. To add custom headers, use the `defaultHeaders`
setting in your connector configuration. Specify each custom header with the
prefix `defaultHeaders:` followed by the header name.

**Example**:

```json
{
  "defaultHeaders:X-API-Key": "your-api-key-here",
  "defaultHeaders:X-Tenant-ID": "production-tenant",
  "defaultHeaders:X-Source-System": "KurrentDB"
}
```

With this configuration, the connector includes the custom headers and their
values in every HTTP request. It sends them alongside the
[default headers](/kurrent-surge/client/connectors/sinks/#headers) that its plugin adds automatically.

## Template parameters

The HTTP sink supports template parameters in the URL, so the connector builds
the request URL from record data. Customize the destination URL for each record
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 record's schema subject, converted to lowercase with hyphens |
| `{event-type}`     | Alias for `{schema-subject}`                                    |
| `{stream}`         | The KurrentDB stream ID                                         |

**Usage**

To use template parameters, include them in the `Url` option of your HTTP sink configuration. The connector replaces
each parameter with its corresponding value for every record.

Example:

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

For a record with schema subject "TestEvent", the URL becomes:

```
https://api.example.com/test-event
```

## Tutorial

[Learn how to configure and use a connector using the HTTP Sink in KurrentDB through a tutorial.](https://docs.kurrent.io/server/v26.1/tutorials/HTTP_Connector)