<!-- Source: https://docs.svix.com/account/environments -->

---
title: Managing Environments
---
# Managing Environments


This section explains how to add and use multiple environments (e.g. dev, staging, and prod) from the same account.

## What are environments

It's common practice for engineering teams to have multiple environments, such as development, staging, and production. The idea behind having multiple environments is to be able to test changes in isolation and catch issues before they hit production. So for example, a developer may make some changes locally, test them, and push them for testing in CI/CD. Following that, the change will be moved to a shared `development` environment where it would be tested by the wider team. Changes that pass this level of testing will move to `staging`, where they are deployed to an environment that's as similar as possible to the `production` environment, and after all testing pass there they would be deployed to `production` and rolled out to users.

Not all teams go through all of the steps above (and some go through more), but the idea remains the same: you want to isolate your `production` environment, where real user data lies, from your non-production environments that may contain bugs and regressions.

## Managing environments

Your Svix environments are completely isolated and have separate data, settings, and API keys.

You can create as many environments as you want from the [Environment Management page](https://dashboard.svix.com/environments) on the dashboard.

### Add environments

Click on `New Environment`, choose a name, mark the environment as either `Development` or `Production`, and choose the wanted region.

![New environment](./environments/env-add.png)

Development and Production environments behave almost exactly the same. The main difference is the associated tag and the visual indicator, as well as some other minor differences.

![Preview App Portal](/img/dashboard-preview-button.png)

### View environments

This is how it looks like after adding multiple environments:

![Manage environments](./environments/env-manage.png)

You can then switch between the active environment using the switcher on the top left corner and just start using that environment like you used your account before.

### Environment-specific settings

When configuring your environments, it's important to know which settings are shared across your environments and which are kept separate. On the settings page, there is a separate section for "environment-specific" settings.

![environment specific settings](/img/env-specific-settings.png)

#### App Portal White Labeling

The App Portal [White Labeling](../app-portal#white-labeling) is configured separately for each environment. This allows you to experiment with how the App Portal will look in your development environment without affecting your production users.

#### HTTPS Only Endpoints

It is strongly recommended that all registered endpoints in production environments are secured with HTTPS. If you want to allow unsecure endpoints (HTTP) on any environment, you may do so on the "General Settings" page.

As of October 1st, 2021, HTTPS Only Endpoints is enabled by default on newly created environments. If your environment was created before then, the default was disabled and your environment was left unchanged.


## Environment import & export

Import and export makes it very easy to clone (or sync) environments, and thus make sure that your staging and production environments are identical. It also makes it possible to save your environment settings in version control in order to make sure you keep track of changes to your environment.

Export currently supports the environment settings as well as all of the event types. To import and export, all you need to do is to go to the [environment management](https://dashboard.svix.com/environments) page on the dashboard, choose the wanted environment from the list, and then click either import or export.

![Import and export from an environment](/img/import-export.png)


<!-- Source: https://docs.svix.com/account/org-members -->

---
title: Managing Member Access
---
# Managing Member Access


This section explains how to manage access to your organization's account. You can easily give your teammates access, manage it, and invite new team members.

## Managing members

There are currently four supported roles: `Viewer`, `Support Agent`, `Member` and `Admin`.
- A `Viewer` has basic privileges and can view statistics and basic configurations but can't access API keys.
- A `Support Agent` can preview [Consumer App Portals](../app-portal), in addition to having the same permissions as a `Viewer`.
- A `Member` can control most aspects of the account, including applications, endpoints and event types.
- An `Admin` can do all of that, and also manage members.

You can invite as many members as you want to your organization, so feel free to invite all of your team. To do it, go to the [organization members page](https://dashboard.svix.com/settings/organization-group/members) on the dashboard.

### Invite a user

Click on `Invite Teammates`, put in the email address of the teammate you would like to invite, and choose the appropriate role.

![New member](./org-members/add-member.png)

Svix will then send an invitation to the provided email address.

### Accept an invitation

Once your teammate receives the invitation via email, they can follow the link to decide whether to accept or decline the invitation. Accepting the invitation will remove the recipient from their current account and add them to the new account. Declining the invitation will expire it.

The recipient's email must be verified before they can accept an invitation.

### View members

This is how it looks like after you've sent some invitations:

![Manage members](./org-members/manage-members.png)

You can then add more members, manage access and manage invitations directly from this page.


<!-- Source: https://docs.svix.com/advanced-endpoints/bigquery -->

---
title: Google BigQuery
---
# Google BigQuery

Svix can deliver webhooks directly to a Google BigQuery table, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use a BigQuery destination in the [App Portal](/app-portal).

![BigQuery Endpoint Create](/img/advanced-endpoints/bigquery-create.png)

They will be able to configure the connection right in the App Portal:

- `projectId` — the GCP project that owns the dataset.
- `datasetId` — the BigQuery dataset that contains the table.
- `tableId` — the table that receives the rows.
- `credentials` — a Google Cloud service account credentials JSON object, provided as a string.

Every batch of webhooks received by the endpoint is inserted into the configured BigQuery table.

## Destination table

Without a transformation, Svix inserts each webhook into the table identified by `projectId`, `datasetId`, and `tableId` using two columns: `id` and `payload`. Svix generates a unique `id` for each row and writes the raw payload to `payload`.

The table must already exist before you enable the endpoint. For the default behavior, create it with:

```sql
CREATE TABLE `my-gcp-project.my_dataset.events` (
  id STRING,
  payload STRING
);
```

If you use a transformation (below), you control the columns each row contains, so your table can use any schema you like — as long as it matches the rows your transformation returns.

# Transformations

Each webhook is inserted into BigQuery as a row. A transformation returns the `rows` to insert, where each row is an object whose keys match your table's columns.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the rows to insert.
 * @returns returns.rows - The array of rows to insert. Each row is an object whose keys match the columns of your BigQuery table.
 */
function handler(input) {
    const rows = input.events.map((event) => ({
        id: crypto.randomUUID(),
        payload: JSON.stringify(event.payload)
    }));

    return { rows };
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

Each entry in the returned `rows` array is inserted as a separate row. The object keys must match the column names of your table. To write different columns, adjust the objects in `rows` and your table schema to match.

For example, if the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"email\": \"joe@enterprise.io\"}"
}
```

```json
{
  "eventType": "user.login",
  "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
}
```

The transformation above inserts two rows into your table.

| `id` | `payload` |
| --- | --- |
| `1f0a8c1e-...` | `{"email":"joe@enterprise.io"}` |
| `4b9d2e7a-...` | `{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"}` |


<!-- Source: https://docs.svix.com/advanced-endpoints/clickhouse -->

---
title: ClickHouse
---
# ClickHouse

Svix can deliver webhooks directly to a ClickHouse table, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use a ClickHouse destination in the [App Portal](/app-portal).

![ClickHouse Endpoint Create](/img/advanced-endpoints/clickhouse-create.png)

They will be able to configure the connection right in the App Portal:

- `url` — the HTTP URL of your ClickHouse server (e.g. `https://my-clickhouse.example.com:8443`).
- `username`, `password` — the credentials used to authenticate.
- `tableName` — the table that receives the rows.
- `database` — the database that contains the table. Defaults to `default`.

Every batch of webhooks received by the endpoint is inserted into the configured ClickHouse table.

## Destination table

Without a transformation, Svix inserts each webhook's payload directly into the table using ClickHouse's [`JSONEachRow`](https://clickhouse.com/docs/interfaces/formats/JSONEachRow) format. The top-level fields of each payload must match the columns of your table.

The table must already exist before you enable the endpoint. For example, for payloads shaped like `{"email": "...", "username": "..."}`, create the table with:

```sql
CREATE TABLE events (
  email String,
  username String
)
ENGINE = MergeTree()
ORDER BY tuple();
```

Unlike some other warehouse destinations, ClickHouse does not add any columns of its own — you define the full schema, and the payload fields are matched to it by name.

# Transformations

If your payloads don't already match your table's columns, add a transformation that returns the `rows` to insert. Each row is an object whose keys match your table's columns.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the rows to insert.
 * @returns returns.rows - The array of rows to insert. Each row is an object whose keys match the columns of your ClickHouse table.
 */
function handler(input) {
    const rows = input.events.map((event) => ({
        email: event.payload.address,
        username: event.payload.handle
    }));

    return { rows };
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

Each entry in the returned `rows` array is inserted as a separate row using `JSONEachRow`, so the object keys must match the column names of your table.

For example, if the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"address\": \"joe@enterprise.io\", \"handle\": \"joe\"}"
}
```

```json
{
  "eventType": "user.created",
  "payload": "{\"address\": \"amy@enterprise.io\", \"handle\": \"amy\"}"
}
```

The transformation above inserts two rows into your table, mapping each payload's `address` and `handle` fields onto the `email` and `username` columns.

| `email` | `username` |
| --- | --- |
| `joe@enterprise.io` | `joe` |
| `amy@enterprise.io` | `amy` |


<!-- Source: https://docs.svix.com/advanced-endpoints/eventbridge -->

---
title: Amazon EventBridge
---
# Amazon EventBridge

Svix can deliver webhooks directly to Amazon EventBridge, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use an EventBridge destination in the [App Portal](/app-portal).

![EventBridge Endpoint Create](/img/advanced-endpoints/eventbridge-create.png)

They will be able to configure the connection right in the App Portal:

- `eventBusName` — the name or ARN of the event bus that receives the events.
- `detailType` — a free-form string (max 128 characters) used as the `detail-type` of each event. Defaults to `application/json`.
- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.

Every webhook in the batch is sent to EventBridge as a separate entry.

Each event is published with its `source` set to `svix-webhooks-<app_id>`, its `detail-type` set to the configured `detailType`, and its `detail` set to the message produced by the transformation. You can match on the `source` and `detail-type` when writing EventBridge rules.

# Transformations

By default, all EventBridge Endpoints come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object containing the request body
 * @returns returns.payloads - The array of messages (strings) to send to the endpoint. Each payload is a distinct message sent to EventBridge.
 */
function handler(input) {

  const payloads = input.events.map((event) => JSON.stringify(event))

  return {
    payloads
  }
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

Each entry in the returned `payloads` array becomes the `detail` of a separate EventBridge event. By default, each webhook is serialized to a JSON string containing its `payload` and `eventType`.

For example, if the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"email\": \"joe@enterprise.io\"}"
}
```

```json
{
  "eventType": "user.login",
  "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
}
```

The default transformation code would send two events to your event bus, with the following `detail` bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the `detail` of each event, return your own array of strings in `payloads`. Each string becomes the `detail` of one EventBridge event.

EventBridge accepts at most 10 entries per request, so larger batches are automatically split across multiple `PutEvents` calls.


<!-- Source: https://docs.svix.com/advanced-endpoints/fifo-endpoints -->

---
title: FIFO Endpoints
---
# FIFO Endpoints

FIFO endpoints let your webhook consumers receive webhooks in strict FIFO ordering (first in first out), unlike regular webhooks, which are delivered independently and order is on a best effort basis.

Svix supports sending webhooks to both FIFO and regular endpoints, with no code changes required on your end.

<Callout type="info">

**Why not make all webhooks FIFO?**

Ensuring strict FIFO ordering comes with some tradeoffs. Since every call to the receiver endpoint is blocked until the previous one is successful, throughput is limited compared to regular webhook endpoints.

Read more about [how FIFO endpoints work](https://www.svix.com/blog/fifo-ordered-webhooks-delivery/) and [the challenges with guaranteeing webhook ordering](https://www.svix.com/blog/guaranteeing-webhook-ordering/).

</Callout>
## Enabling FIFO Endpoints
FIFO Endpoints can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings) by enabling **Advanced Endpoint Types**.

![Enable FIFO Endpoints](/img/advanced-endpoints/advanced-endpoints-setting.png)


When you enable FIFO Endpoints, your users will be able to create them in the [App Portal](/app-portal).

![Polling Endpoint Create](/img/advanced-endpoints/fifo-endpoint-create.png)

## Message Batching
Because of the strict ordering, Svix has to wait for a successful acknowledgement of delivery before sending any other messages. To address throughput constraints FIFO endpoints deliver webhooks in configurable batch sizes.

The batching parameters can be configured in the [App Portal](/app-portal) for each endpoint.

![FIFO Endpoint Batching](/img/advanced-endpoints/fifo-endpoint-batching.png)

## Transformations
[Transformations](/transformations) are also supported on FIFO endpoints. For FIFO endpoints, transformations are applied to each batch of messages.

### How to write a FIFO endpoint transformation
Svix expects a Transformation to declare a function named `handler`. Svix will pass a `InputObject` to this function as its only argument, and expects the function to always return an `OutObject`.

`InputObject` is a JSON object containing one property:

- `events`, an array of objects containing `payload` and `eventType` properties. There is one element in the array for each message in the batch.

`OutObject` is a JSON object containing one property:

- `requestBody`, a string with the raw request body to be sent to the endpoint.

### An example Transformation

You can write a transformation that transforms certain messages in the batch and forwards them.

```js
function handler(input) {
  const events = input.events.map((evt) => {
    if (evt.eventType === "user.created") {
      return {
        ...evt.payload,
        name: evt.payload.firstName + " " + evt.payload.lastName
      }
    }
  });

  return {
    requestBody: JSON.stringify({ data: events })
  }
}
```

Or you can write transformations that collect messages and returns a summarized response.

```js
function handler(input) {
  const total = input.events.reduce((acc, evt) => {
    if (evt.eventType === "invoice.created") {
      return acc + evt.payload.amount;
    }
    return acc;
  }, 0);

  return {
    requestBody: JSON.stringify({ total })
  }
}
```


<!-- Source: https://docs.svix.com/advanced-endpoints -->

---
title: Advanced Endpoint Types
asIndexPage: true
---
# Advanced Endpoint Types

Svix supports multiple types of endpoints in addition to regular webhook endpoints, to support different use cases.

- [Polling Endpoints](/advanced-endpoints/polling-endpoints)
- [FIFO Endpoints](/advanced-endpoints/fifo-endpoints)
- [Object Storage](/advanced-endpoints/object-storage)
- [OpenTelemetry Tracing](/advanced-endpoints/otel-tracing)
- [Snowflake](/advanced-endpoints/snowflake)
- [RabbitMQ](/advanced-endpoints/rabbitmq)
- [Amazon EventBridge](/advanced-endpoints/eventbridge)
- [Amazon SNS](/advanced-endpoints/sns)
- [Amazon SQS](/advanced-endpoints/sqs)
- [Google BigQuery](/advanced-endpoints/bigquery)
- [ClickHouse](/advanced-endpoints/clickhouse)
- [Amazon Redshift](/advanced-endpoints/redshift)

## Enabling Advanced Endpoint Types

Advanced Endpoint Types can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings).

![Enable Advanced Endpoint Types](/img/advanced-endpoints/advanced-endpoints-setting.png)

When you enable Advanced Endpoint Types, your users will be able to create them in the [App Portal](/app-portal).

![Advanced Endpoint Types](/img/advanced-endpoints/object-storage-endpoints.png)


<!-- Source: https://docs.svix.com/advanced-endpoints/object-storage -->

---
title: Object Storage
---
# Object Storage

Svix supports sending messages directly to [AWS S3](https://aws.amazon.com/s3/), [Google Cloud Storage](https://cloud.google.com/storage) and [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs).

This is useful for storing payloads in a cloud storage bucket without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use object storage destinations in the [App Portal](/app-portal).

![Object Storage Endpoint Create](/img/advanced-endpoints/object-storage-endpoints.png)

They will be able to configure the connection right in the App Portal.

![Object Storage Endpoint Create](/img/advanced-endpoints/s3-configuration.png)

## Usage

By default, all Object Storage Endpoints come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Object Storage Endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing what will be put to the bucket.
 * @returns returns.config
 * @returns returns.config.format - The format of the request object put to the bucket. Valid values are "jsonl", "json", or "raw" (Defaults to jsonl).
 * @returns returns.config.key - The name of the object that will be put to the bucket. This will be suffixed with a timestamp to avoid duplicate object names.
 * @returns returns.data - The array of events to send to the bucket. This will be formatted according to the format.
 */
function handler(input) {
    return {
        config: {
            format: "jsonl",
            key: "object-generated-by-svix"
        },
        data: input.events
    }
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

`config` describes the object put in the destination - the key name of the object, and the format of the object saved to the bucket.

By default, the actual object key is always suffixed with a timestamp after the transformations are run. This ensures each event batch is saved as a unique object in the bucket.

For example, if the endpoint receives the following events:

```json
{
  "eventType": "user.created",
  "payload": "{\"email\": \"joe@enterprise.io\"}"
}
```

```json
{
  "eventType": "user.login",
  "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
}
```

The default transformation code would result in the following object being uploaded to the bucket.

![s3-recent-events](/img/stream/s3-example.png)

And the files contents would match the jsonl format.

```jsonl
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

If you want to control the format of the object more precisely, you can use `config.format = "raw"`, and set `data` to a string of the exact file contents you want.


<!-- Source: https://docs.svix.com/advanced-endpoints/otel-tracing -->

---
title: OpenTelemetry Tracing
---
import OpenTelemetryProviderNotes from '../_common/otel-provider-notes.mdx'

# OpenTelemetry Tracing

Svix can deliver webhooks directly to an OpenTelemetry tracing collector as spans, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use an OpenTelemetry destination in the [App Portal](/app-portal).

![OpenTelemetry Endpoint Create](/img/advanced-endpoints/otel-create.png)

They will be able to configure the connection right in the App Portal:

- `url` — the collector endpoint. Typically this is the `OTEL_EXPORTER_OTLP_ENDPOINT` URL given by your OpenTelemetry provider, appended with `/v1/traces`, following the [conventions of OTLP exporters](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint).

Just like with regular webhook endpoints, you can configure the OpenTelemetry endpoint with custom headers that will be injected on each request.

![otel-headers](/img/stream/otel-headers.png)

# Transformations

By default, all OpenTelemetry Endpoints come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the otel spans to be created.
 * @returns returns.config
 * @returns returns.config.serviceName - The name of the otel service.
 * @returns returns.config.scope - The scope of the otel service. Includes a name and version string.
 * @returns returns.spans - Array of objects, each describing an otel span.
 * @returns returns.spans[].kind - The kind of span. Can be one of "SERVER", "CLIENT", "PRODUCER", "CONSUMER", or "INTERNAL". (Defaults to "INTERNAL")
 * @returns returns.spans[].traceIdKey - An optional string. Attaches the span to traces with the same traceIdKey.
 * @returns returns.spans[].spanIdKey - An optional string. Identifies the span.
 * @returns returns.spans[].parentSpanIdKey - An optional string. Attaches the span to a parent with the same spanIdKey.
 * @returns returns.spans[].startTime - The start time of the span. Must be a string in ISO 8601 format.
 * @returns returns.spans[].endTime - The end time of the span. Must be a string in ISO 8601 format.
 * @returns returns.spans[].name - The name of the span.
 * @returns returns.spans[].attributes - An optional object. Contains key-value pairs of attributes.
 */
function handler(input) {
    const spans = input.events.map((event) => {
        return {
            // The start and end times of the span.
            // You'll likely want to override these based on values from the event.payload.
            startTime: new Date().toISOString(),
            endTime: new Date().toISOString(),

            name: event.eventType,
            attributes: event.payload
        }
    })

    return {
        config: {
            serviceName: "svix.webhooks",
            scope: {
                name: "svix.webhooks",
                version: "0.0.1"
            },
        },
        spans
    }
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

`config` describes the [service](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-name) and [scope attributes and definitions](https://opentelemetry.io/docs/concepts/instrumentation-scope/) that all tracing data are grouped under.

`spans` is an array of [OpenTelemetry spans](https://opentelemetry.io/docs/concepts/signals/traces/#spans). Each span has the following properties:

* `startTime` and `endTime`: These mark the start and end of the span. By default, they are set to the current timestamp, so you'll likely want to derive these from your events directly.
* `kind`: One of `"SERVER"`, `"CLIENT"`, `"PRODUCER"`, `"CONSUMER"`, or `"INTERNAL"` (`"INTERNAL"` is the default). For more details on the meaning behind these values, see [OpenTelemetry - Span Kinds](https://opentelemetry.io/docs/concepts/signals/traces/#span-kind)
* `name`: A string, denoting the name of the span.
* `attributes`: key-value pairing of attributes for the span. These can be any values you want associated with your span.
* `traceIdKey`: By default, each span is assigned it's own trace ID that is randomly generated by Svix.
However, you can specify a `traceIdKey` to derive a fixed key for the given span. This allows you to correlate multiple spans to the same trace.
* `spanIdKey`: Uniquely identifies a `span` with a fixed key. By default, Svix will use a randomly generated ID if left unspecified.
* `parentSpanIdKey`: Attaches the span as a child, to another span with the `spanIdKey` set to the same value. This allows you to set child spans.


# Example

To better understand how you can use OpenTelemetry Endpoints, let's walk through an example use case where you want to send webhook dispatch telemetry to a cloud observability platform like Grafana.

Your service may produce webhooks that look like the following:

```json
{
  "eventType": "message.attempt",
  "payload": {
    "appId": "app_379",
    "msgId": "msg_1234",
    "attemptId": "atmpt_9876",
    "startTime": "2025-08-19T15:24:53.291Z",
    "endTime": "2025-08-19T15:24:56.291Z"
  }
}
```

```json
{
  "eventType": "http.attempt",
  "payload": {
    "msgId": "msg_1234",
    "attemptId": "atmpt_9876",
    "startTime": "2025-08-19T15:24:54.291Z",
    "endTime": "2025-08-19T15:24:55.291Z"
  }
}
```

```json
{
  "eventType": "message.attempt",
  "payload": {
    "appId": "app_379",
    "msgId": "msg_5678",
    "attemptId": "atmpt_1224",
    "startTime": "2025-08-19T15:24:51.291Z",
    "endTime": "2025-08-19T15:24:54.291Z"
  }
}
```

```json
{
  "eventType": "http.attempt",
  "payload": {
    "msgId": "msg_5678",
    "attemptId": "atmpt_1234",
    "startTime": "2025-08-19T15:24:52.291Z",
    "endTime": "2025-08-19T15:24:53.291Z"
  }
}
```

Here, the webhooks model message deliveries. Note that:
* We have two distinct messages being sent (distinct `msgId`s), each with their own attempt. Each attempt has a clear start and end time.
* The `http.attempt` happens within a `message.attempt`. In other words, `http.attempt` is a child span of `message.attempt`.

In order to ensure that each message is grouped into its own distinct trace, and that `http.attempt`s are correctly marked as child spans of `message.attempt`s,
we'll use the following transformation code.

```JavaScript
function handler(input) {
    const spans = input.events.map((event) => {
        const payload = event.payload
        return {
            // start and end times are extracted from the event directly.
            startTime: payload.startTime,
            endTime: payload.endTime,

            // We use the eventType as the name of the span,
            // as it makes it easier to identify which events map to
            // which spans in your OpenTelemetry platform.
            name: event.eventType,

            // We use the msgId as the traceIdKey, to ensure that all spans for the same
            // message are correctly grouped into the same trace.
            traceIdKey: payload.msgId,

            // Because we want to `http.attempt` to be a child span of the `message.attempt`, we
            // use the `attemptId` to mark the parent and child spans, respectively.
            spanIdKey: event.eventType === "message.attempt" ? payload.attemptId : undefined,
            parentSpanIdKey: event.eventType === "http.attempt" ? payload.attemptId : undefined,

            // Attributes can be anything you want. Here, we extract the important ID's from the event payload.
            attributes: {
              msgId: payload.msgId,
              appId: payload.appId,
              attemptId: payload.attemptId
            }
        }
    })

    // Note that your `service.name` has been configured to `my.webhook.service`, and each individual webhook received by the endpoint is treated as its own span.
    return {
        config: {
            serviceName: "my.webhook.service",
            scope: {
                name: "my.webhook.scope",
                version: "2.0"
            },
        },
        spans
    }
}
```

When the endpoint receives these webhooks, they'll be dispatched to your observability platform.

In this Grafana view, we can see `msg_1234` as its own isolated trace, with the `message.attempt` and `http.attempt` spans correctly grouped together, with the expected attributes.

![grafana-example](/img/stream/grafana-dashboard.png)

<OpenTelemetryProviderNotes />


<!-- Source: https://docs.svix.com/advanced-endpoints/polling-endpoints -->

---
title: Polling Endpoints
---
# Polling Endpoints

Polling Endpoints are a way for your users to get a stream of events by polling instead of listening to webhooks.

## When is polling better?

There are a few examples where polling for events works better than webhooks.

One example is when testing webhooks locally. It's much easier to poll for events than exposing a public HTTP endpoint (even with tools like [Svix Play](/play) or [ngrok](/integrations/ngrok)).

Another example is when your users don't care about getting events in real-time and prefer getting them all at once at the end of a day. One place where this use-case comes up, is when your users need to store all events for compliance reasons. In that case batching and saving them all at once is easier and more cost efficient for them.

## Enabling Polling Endpoints

Polling Endpoints can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings) by enabling **Advanced Endpoint Types**.

![Enable Polling Endpoints](/img/advanced-endpoints/advanced-endpoints-setting.png)

When you enable Polling Endpoints, your users will be able to create them in the [App Portal](/app-portal).

![Polling Endpoint Create](/img/advanced-endpoints/polling-endpoint-create.png)

## Usage

Like with webhook endpoints, Polling Endpoints support filtering messages by [event types](/event-types) and [channels](/channels).

In the App Portal, consumers will get a unique URL and an API key to iterate through the full list of events sent to their [Svix Application](/overview#consumer-applications) since the endpoint was created.

When creating a Polling Endpoint, consumers will get a unique URL like `https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/{consumer_id}`

This URL can be polled to receive messages for a given `Consumer ID`. Each consumer tracks its own progress independently.

```bash
curl \
  -X GET "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/MY_CONSUMER_ID" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer sk_poll_*****.eu'
```

Each message includes an `offset`. Messages are returned in the order they were received.

```json
{
  "data": [{
    "id": "msg_2K2N9Qk...",
    "eventType": "invoice.created",
    "payload": { "hello": "world" },
    "timestamp": "2025-01-17T00:00:00.000Z",
    "offset": 0
  }],
  "done": true
}
```

After processing a batch, commit the last message's `offset` so the next poll continues from there.

```bash
curl \
  -X POST "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/MY_CONSUMER_ID/commit" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_poll_*****.eu' \
  -d '{ "offset": 0 }'
```

Until you commit, the same messages may be returned again after the lease expires. Use a stable `Consumer ID` per worker so progress is preserved across restarts.

> Consumer IDs are arbitrary strings used by a client to self-identify.
>
> Note that Consumer IDs should be _unique per client_ and should not be shared. Put another way, Consumer IDs track
> exclusive sequential access through the stream of messages.
> Shared concurrent access through a given Consumer ID will result in errors as mutual clients drift in their positions
> in the stream.

## Usage with Svix Bridge

If you have a service that must not be exposed on the public internet and you want it to receive webhooks from Svix, you can deploy a [Svix Bridge] instance inside the same network that
forwards messages from a polling endpoint to the destination service.
Svix Bridge will take care of retrying in case the connection the Svix API
or the destination service is temporarily lost.

The app portal page for the Polling Endpoint includes a basic example config for Svix Bridge,
with the app ID and sink ID already filled in. It looks like this:

```yaml
receivers:
  - name: "msg-poller-to-http"
    input:
      type: "svix-message-poller"
      consumer_id: "svix-bridge-1"
      app_id: "app_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
      sink_id: "poll_yyy"
      token: "sk_poll_*****.eu"
    output:
      type: "http"
      url: "http://example.local"
```

The http output is not the only destination Svix Bridge can send webhooks to,
it can also store them to a messaging system like RabbitMQ or Kafka.
Further, you can set a transformation - a small JS program that processes each message
before it gets forwarded.

For the full list of supported configuration options and how to configure each of the output types,
see the [receivers example config file][example-recv-cfg].

[Svix Bridge]: https://github.com/svix/svix-webhooks/tree/main/bridge#readme
[example-recv-cfg]: https://github.com/svix/svix-webhooks/blob/main/bridge/svix-bridge.example.receivers.yaml

---

Polling Endpoints can be used in parallel with regular Svix webhooks, and you don't need to make any changes to how you [create messages](/quickstart#send-a-message).


<!-- Source: https://docs.svix.com/advanced-endpoints/rabbitmq -->

---
title: RabbitMQ
---
# RabbitMQ

Svix can deliver webhooks directly to RabbitMQ, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use a RabbitMQ destination in the [App Portal](/app-portal).

![RabbitMQ Endpoint Create](/img/advanced-endpoints/rabbitmq-create.png)

They will be able to configure the connection right in the App Portal:

- `uri` — the AMQP connection URI for your RabbitMQ instance.
- `routingKey` — the routing key each message is published with.

Every webhook in the batch is published to RabbitMQ as a separate message, using the `routingKey` from the config.

# Transformations

By default, all RabbitMQ Endpoints come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object containing the request body
 * @returns returns.payloads - The array of messages (strings) to send to the endpoint. Each payload is a distinct message published to RabbitMQ.
 */
function handler(input) {

  const payloads = input.events.map((event) => JSON.stringify(event))

  return {
    payloads
  }
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

Each entry in the returned `payloads` array is published to RabbitMQ as a separate message. By default, each webhook is serialized to a JSON string containing its `payload` and `eventType`.

For example, if the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"email\": \"joe@enterprise.io\"}"
}
```

```json
{
  "eventType": "user.login",
  "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
}
```

The default transformation code would publish two messages to your `routingKey`, with the following bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the message bodies, return your own array of strings in `payloads`. Each string becomes one message.


<!-- Source: https://docs.svix.com/advanced-endpoints/redshift -->

---
title: Amazon Redshift
---
# Amazon Redshift

Svix can deliver webhooks directly to an Amazon Redshift table, without your customers having to set up any listener endpoint or write any glue code. Svix writes to Redshift through the [Redshift Data API](https://docs.aws.amazon.com/redshift-data/latest/APIReference/Welcome.html), and supports both Redshift Serverless and provisioned clusters.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use a Redshift destination in the [App Portal](/app-portal).

![Redshift Endpoint Create](/img/advanced-endpoints/redshift-create.png)

They will be able to configure the connection right in the App Portal:

- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.
- `dbName` — the database to write to.
- `schemaName` — the schema that contains the table (optional).
- `tableName` — the table that receives the rows.

Every batch of webhooks received by the endpoint is inserted into the configured Redshift table.

## Connection

How you point Svix at your Redshift depends on the deployment type:

- **Redshift Serverless** — set `workgroupName` to the name of your workgroup.
- **Provisioned clusters** — set `clusterIdentifier` to your cluster's identifier and `dbUser` to the database user to connect as.

## Destination table

Without a transformation, Svix inserts each webhook into the table identified by `dbName`, `schemaName`, and `tableName` using two columns: `created_at` and `payload`. Svix sets `created_at` to the insert time and writes the raw payload to `payload`.

The table must already exist before you enable the endpoint. For the default behavior, create it with:

```sql
CREATE TABLE events (
  created_at TIMESTAMP,
  payload VARCHAR(65535)
);
```

At the time of writing, `VARCHAR(65535)` is the largest allowable `VARCHAR` size in Redshift. If webhooks with larger payloads are received by the endpoint, the endpoint will be disabled since these payloads can't be written to Redshift.

The `dbName`, `schemaName`, and `tableName` fields are only required when you're not using a transformation. With a transformation, the target table is named directly in your statement.

# Transformations

Redshift transformations build a parameterized SQL statement. The transformation returns the `statement` to run and the `bindings` it references.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the SQL to run against Redshift.
 * @returns returns.statement - The SQL statement to execute. Reference parameters by name (e.g. :payload0).
 * @returns returns.bindings - The parameters referenced by the statement. Each binding is an object with a `name` and a `value`.
 */
function handler(input) {
    let bindings = [];
    let values = [];

    input.events.forEach((event, i) => {
        const name = `payload${i}`;
        bindings.push({ name: name, value: JSON.stringify(event.payload) });
        values.push(`(CURRENT_TIMESTAMP, :${name})`);
    });

    return {
        bindings: bindings,
        statement: `INSERT INTO events (created_at, payload) VALUES ${values.join(", ")};`
    };
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

`bindings` is an array of `{ name, value }` parameters, and the `statement` references them by name (e.g. `:payload0`). The statement is run against your database through the Redshift Data API. To write different columns, adjust the `bindings`, the `statement`, and your table to match.

For example, if the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"email\": \"joe@enterprise.io\"}"
}
```

```json
{
  "eventType": "user.login",
  "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
}
```

The transformation above inserts two rows into your table.

| `created_at` | `payload` |
| --- | --- |
| `2025-07-21 14:23:18` | `{"email":"joe@enterprise.io"}` |
| `2025-07-21 14:23:18` | `{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"}` |


<!-- Source: https://docs.svix.com/advanced-endpoints/snowflake -->

---
title: Snowflake
---
# Snowflake

Svix can deliver webhooks directly to a Snowflake table, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use a Snowflake destination in the [App Portal](/app-portal).

![Snowflake Endpoint Create](/img/advanced-endpoints/snowflake-create.png)

They will be able to configure the connection right in the App Portal:

- `accountIdentifier` — your Snowflake account identifier in `<organization>-<account>` form (e.g. `ab12345-xs67890`).
- `userId` — the Snowflake user the public key is assigned to.
- `privateKey` — the PEM-encoded private key.
- `dbName`, `schemaName`, `tableName` — the database, schema, and table that receive the rows.

Every batch of webhooks received by the endpoint is inserted into the configured Snowflake table.

## Authentication

Svix authenticates to Snowflake using [key-pair (JWT) authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth). Generate an RSA key pair, assign the public key to a Snowflake user, and provide the matching private key in the endpoint config.

## Destination table

Without a transformation, Svix inserts each webhook into the table identified by `dbName`, `schemaName`, and `tableName` using three columns: `id`, `created_at`, and `payload`. Svix generates a unique `id` for each row, sets `created_at` to the insert time, and writes the raw payload to `payload`.

The table must already exist before you enable the endpoint, which you can create with the following sql:

```sql
CREATE TABLE my_database.my_schema.my_table (
  id TEXT,
  created_at TIMESTAMP,
  payload TEXT
);
```

If you use a transformation (below), you control the SQL that runs, so `dbName`, `schemaName`, and `tableName` become optional — the target table is named directly in your statement.

# Transformations

Snowflake Endpoints shape each batch of webhooks into a SQL `INSERT` statement. The transformation returns the `statement` to run and the `bindings` it references.

For example, suppose you have a table with the following structure:

```sql
CREATE TABLE testdb.testschema.users (
  name TEXT,
  age INT
);
```

If the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"name\": \"John Smith\", \"age\": 34}"
}
```

```json
{
  "eventType": "user.created",
  "payload": "{\"name\": \"Jane Doe\", \"age\": 47}"
}
```

To insert the new users into your `testdb.testschema.users` table, you'd write transformation code as follows:

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the SQL to run against Snowflake.
 * @returns returns.statement - The SQL statement to execute. Reference bindings by name (e.g. :id), matching the keys in `bindings`.
 * @returns returns.bindings - The bindings referenced by the statement. Each binding has a Snowflake `type` (e.g. "TEXT") and a column-oriented `value` array with one entry per row in the batch.
 */
function handler(input) {
    let bindings = {
        "name": { "type": "TEXT", "value": [] },
        "age": { "type": "FIXED", "value": [] },
    };

    input.events.forEach((event) => {
        let name = event.payload.name;
        let age = String(event.payload.age); // Note that Snowflake requires all values be sent as Strings
        bindings.name.value.push(name);
        bindings.age.value.push(age);
    });

    return {
        bindings: bindings,
        statement: "INSERT INTO TESTDB.TESTSCHEMA.users (name, age) VALUES (:name, :age);"
    };
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

`bindings` are column-oriented: each binding lists a Snowflake `type` and a `value` array holding one entry per row in the batch. The `statement` references them by name (`:name` and `:age`). For more information which types are allowed, see [Using bind variables in a statement.](https://docs.snowflake.com/en/developer-guide/sql-api/submitting-requests#using-bind-variables-in-a-statement)

Because the statement names the table directly, `dbName`, `schemaName`, and `tableName` are optional when a transformation is set. To write different columns, adjust the `bindings`, the `statement`, and your table to match.

The transformation above would insert two rows into your table.

![snowflake-output](/img/stream/snowflake-output.png)


<!-- Source: https://docs.svix.com/advanced-endpoints/sns -->

---
title: Amazon SNS
---
# Amazon SNS

Svix can deliver webhooks directly to an Amazon SNS topic, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use an SNS destination in the [App Portal](/app-portal).

![SNS Endpoint Create](/img/advanced-endpoints/sns-create.png)

They will be able to configure the connection right in the App Portal:

- `topicArn` — the ARN of the SNS topic to publish to.
- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.

Every webhook in the batch is published to the topic as a separate message.

# Transformations

By default, all SNS Endpoints come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON).
 * @param input.events[].eventType - The message event type (string).
 *
 * @returns Object containing the response.
 * @returns returns.messages - The array of SNS messages to send to the SNS topic.
 * @returns returns.messages[].payload - The content of the message (string).
 * @returns returns.messages[].subject - An optional subject of the message (string).
 */
function handler(input) {
  const messages = input.events.map((event) => ({
    payload: event,
  }));

  return {
    messages,
  };
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

Each entry in the returned `messages` array is published as a separate SNS message. The `payload` becomes the message body, and the optional `subject` becomes the SNS subject. By default, each webhook is published as its serialized JSON, with no subject.

For example, if the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"email\": \"joe@enterprise.io\"}"
}
```

```json
{
  "eventType": "user.login",
  "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
}
```

The default transformation code would publish two messages to your topic, with the following bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the message bodies, or to set a subject, return your own array of `messages`. Each message's `payload` becomes the body of one SNS message, and `subject` is published as that message's SNS subject.

```JavaScript
function handler(input) {
  const messages = input.events.map((event) => ({
    payload: JSON.stringify(event.payload),
    subject: event.eventType
  }));

  return {
    messages,
  };
}
```

SNS accepts at most 10 messages per batch request, so larger batches are automatically split across multiple `PublishBatch` calls.


<!-- Source: https://docs.svix.com/advanced-endpoints/sqs -->

---
title: Amazon SQS
---
# Amazon SQS

Svix can deliver webhooks directly to an Amazon SQS queue, without your customers having to set up any listener endpoint or write any glue code.

When **Advanced Endpoint Types** is [enabled](/advanced-endpoints#enabling-advanced-endpoint-types), your customers will see the option to use an SQS destination in the [App Portal](/app-portal).

![SQS Endpoint Create](/img/advanced-endpoints/sqs-create.png)

They will be able to configure the connection right in the App Portal:

- `queueUrl` — the full URL of the SQS queue to send messages to.
- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.

Every webhook in the batch is sent to the queue as a separate message.

# Transformations

By default, all SQS Endpoints come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the endpoint's batch size.
 * @param input.events[].payload - The message payload (string or JSON).
 * @param input.events[].eventType - The message event type (string).
 *
 * @returns Object containing the response.
 * @returns returns.messages - The array of SQS messages to send to the SQS queue.
 * @returns returns.messages[].payload - The payload of the message (string).
 */
function handler(input) {
  const messages = input.events.map((event) => ({
    payload: event,
  }));

  return {
    messages,
  };
}
```

`input.events` is the list of webhooks received by the endpoint, processed in batches.

Each entry in the returned `messages` array is sent as a separate SQS message, with its `payload` used as the message body. By default, each webhook is sent as its serialized JSON.

For example, if the endpoint receives the following messages:

```json
{
  "eventType": "user.created",
  "payload": "{\"email\": \"joe@enterprise.io\"}"
}
```

```json
{
  "eventType": "user.login",
  "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
}
```

The default transformation code would send two messages to your queue, with the following bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the message bodies, return your own array of `messages`. Each message's `payload` becomes the body of one SQS message.

SQS accepts at most 10 messages per batch request, so larger batches are automatically split across multiple `SendMessageBatch` calls.


<!-- Source: https://docs.svix.com/ai/agent-quickstart -->

---
title: AI Quickstart
---
# AI Quickstart

Building your Svix integration with an AI coding agent? This is the quickstart for you (well, for it). It gets Claude Code, Cursor, Codex, or any other coding agent set up to build your webhook sending integration: skills, LLM-readable docs, and the CLI. If you're integrating by hand, the regular [Quickstart](/quickstart) is the place to start.

<Callout type="info">

**Sending or receiving?** Svix is webhook *sending* infrastructure, and this page is for platforms sending webhooks to their customers. If you're on the receiving end, consuming webhooks that a Svix-powered provider sends you, connect your agent to the [App Portal MCP](/ai/app-portal-mcp) to debug your deliveries, and use the `receiving-webhooks` skill below when writing your handler.

</Callout>

## Set up your agent

<Steps>

### Install the Svix agent skills

[Agent Skills](https://agentskills.io/) are instructions that load into your agent's context when it touches Svix. Ours teach it to integrate Svix the way our own engineers would: tenancy design, idempotency, App Portal embedding, and the rest.

```bash
npx skills add svix/ai
```

This installs two skills from [svix/ai](https://github.com/svix/ai) into your project:

- **`svix-sending-webhooks`**: everything for building on Svix. First-time setup, sending webhooks to your customers, receiving third-party webhooks with [Ingest](https://www.svix.com/ingest/), and the [Svix CLI](/tutorials/cli). Ask it for a plan and it switches modes: it investigates your repo, asks the questions it can't answer on its own, and writes an integration plan before touching any code.
- **`receiving-webhooks`**: guidelines for writing a webhook handler that verifies signatures correctly. Useful to you when testing your own webhooks end to end, and to your customers when they consume them.

### Create an API key

This is the one step your agent can't do for you. Create a key on the [API Access page](https://dashboard.svix.com/api-access) and set it as an environment variable:

```bash
export SVIX_AUTH_TOKEN="testsk_..."
```

The token encodes your region, so there's no base URL to configure. Keep it server-side; the skills know not to hardcode it.

### Tell it what you want

That's it. Some prompts to start from:

- "Add Svix webhooks to this app. Our customers should get an `invoice.paid` event when a payment settles."
- "Write me a Svix integration plan before we build anything."
- "Define a Svix event type catalog from the events this codebase already emits."
- "Embed the Svix App Portal in our dashboard so customers can manage their own endpoints."

</Steps>

## What Svix gives your agent

| Resource | What it is |
| --- | --- |
| [Agent skills](https://github.com/svix/ai) | Integration instructions that load on demand, installed with `npx skills add svix/ai` |
| LLM-readable docs | Every docs page as markdown, plus [llms.txt](https://docs.svix.com/llms.txt) and [llms-full.txt](https://docs.svix.com/llms-full.txt) indexes |
| [Svix CLI](/tutorials/cli) | The full API from the shell, plus `svix listen` to relay webhooks to localhost |

## Context to paste

If your agent doesn't support skills, or you're working in a chat instead of a repo, use this condensed version of what the skills teach. Save it where your tool looks for instructions:

| Tool | Where it goes |
| --- | --- |
| Claude Code | `CLAUDE.md` |
| Cursor | `.cursor/rules/svix.mdc` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Gemini CLI | `GEMINI.md` |
| Codex, Jules, Amp, and [many others](https://agents.md/) | `AGENTS.md` |
| A chat conversation | paste it directly |

````markdown
# Svix context for AI agents

Svix is webhook-sending infrastructure: you make one API call and Svix
handles delivery, retries, security, and observability. The docs are
agent-readable: append `.md` to any https://docs.svix.com URL; the index
is https://docs.svix.com/llms.txt and the API reference is
https://api.svix.com/docs.

## Core model

- An **Application** is one webhook-receiving tenant, almost always one of
  your customers. Create it with your own customer ID as the `uid` and use
  that `uid` everywhere; you never need to store Svix IDs. Creation is
  idempotent on `uid`.
- An **Endpoint** is a URL an application's messages are delivered to.
  Customers usually manage their own via the App Portal.
- A **Message** is one webhook event, sent to one application and fanned
  out to its endpoints. `eventType` uses a `group.event` convention
  (e.g. `invoice.paid`); include the type in the payload too.
- **Event Types** form your catalog; consumers subscribe per type.

## The three calls that matter

1. `application.create({ name, uid })`: once per customer.
2. `message.create(uid, { eventType, payload })`: to send an event.
3. `authentication.appPortalAccess(uid, {})`: magic link to the App
   Portal, where customers add endpoints, view logs, and replay failures.

## Rules

- `SVIX_AUTH_TOKEN` is server-side only; read it from the environment,
  never hardcode it or expose it to a browser. It encodes the region, so
  no base URL is needed.
- Official SDKs: JavaScript, Python, Go, Rust, Java, Kotlin, Ruby, C#,
  PHP. Same call shapes, different argument conventions; check
  https://docs.svix.com/quickstart.md for the exact syntax per language.
- Make sends idempotent: a deterministic `eventId` per source event, or
  the `Idempotency-Key` header.
- Endpoints must be public HTTPS. For local development run
  `svix listen http://localhost:8000/webhook/` (Svix CLI) to relay
  deliveries to localhost.
- Consumers verify the `svix-signature` header against the **raw**
  request body using the Svix SDK, then return a 2xx within seconds.
- To receive third-party webhooks (Stripe, GitHub, ...) rather than send
  your own, use Svix Ingest:
  https://docs.svix.com/ingest/receiving-with-ingest.md
````

## Agent tools for your webhook consumers

Your customers, the ones receiving your webhooks, get agent tooling of their own. These are worth knowing about because you enable or recommend them:

- The [App Portal MCP](/ai/app-portal-mcp) lets a customer point their coding agent at their deliveries: inspect failed attempts and the exact response their handler returned, fetch real payloads, and replay missed messages. Tokens are scoped to their single application, and you enable the feature per environment from your dashboard.
- [Webhooks AutoConfig](/webhooks-autoconfig) lets a customer's agent configure its own endpoint (URL, event types) in code, with the signing secret bundled into one token, instead of clicking through a UI.
- The [agent plugins](https://github.com/svix/ai#personal-agent-plugins) poll a Svix sink and hand messages to an agent runtime as if they were inbound POSTs, so a laptop behind NAT can receive webhooks without a tunnel.

## LLM-readable docs

Everything on this site is available as plain markdown:

- Append `.md` to any page URL, for example [docs.svix.com/quickstart.md](https://docs.svix.com/quickstart.md).
- [docs.svix.com/llms.txt](https://docs.svix.com/llms.txt): an index of every page with a one-line description, following the [llms.txt convention](https://llmstxt.org/).
- [docs.svix.com/llms-full.txt](https://docs.svix.com/llms-full.txt): the full documentation in one file.

The API reference lives at [api.svix.com/docs](https://api.svix.com/docs), with request and response schemas for every endpoint.


<!-- Source: https://docs.svix.com/ai/app-portal-mcp -->

---
title: Consumer App Portal MCP
---
# Consumer App Portal MCP

The Consumer App Portal MCP server lets your users point their coding agent (Claude Code, Cursor, VSCode, Codex, and others) at their webhooks. Instead of clicking through the Consumer App Portal to figure out why a delivery failed, they can ask their agent.

## Enabling it for your customers

The server is off by default for existing accounts. To turn it on, go to your Svix Dashboard **Settings** -> **General**, and toggle **Enable App Portal MCP**.

This is an environment-level setting, so enable it in each environment (e.g. Development and Production) where you want it available. Once enabled, an **MCP** tab will appear under **Settings** in the App Portal for your customers.

## How your users connect

From the App Portal, your users:

<Steps>

### Open **Settings** -> **MCP**

### Click **Connect to MCP**

This generates an MCP access token and opens a dialog with ready-to-paste setup steps for their coding agent.

### Follow the steps for their agent

The dialog covers a broad list of coding agents. If your agent is missing from this list, please [let us know](https://www.svix.com/contact/)!

</Steps>

The [Connecting Your Coding Agent](/receiving/using-app-portal/connecting-your-coding-agent) guide walks your users through all of this, and you can point them to it directly.

### Connection details

The generated configuration points the agent at the App Portal MCP server for the application:

```
https://mcp.<region>.svix.com/app/<app_id>
```

Where `<region>` is the region your account is in (`us`, `eu`, `ca`, or `au`). The token is sent on every request as an `Authorization: Bearer <token>` header.

The server is named `<slug>-webhooks` in the agent's configuration, where `<slug>` is derived from your App Portal display name (for example `your-company-name-webhooks`), so it's recognizable next to your users' other MCP servers.

For reference, the underlying configuration looks like this in most agents:

```json
{
  "mcpServers": {
    "your-company-name-webhooks": {
      "url": "https://mcp.us.svix.com/app/app_2ErlDgQ1QzKvSAqxdMQnjHNL",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```

## What the agent can do

The server exposes the following tools:

| Tool                        | Purpose                                                                         |
| --------------------------- | ------------------------------------------------------------------------------- |
| `get_application`           | The application this session is scoped to (name, UID, metadata).                  |
| `list_endpoints`            | List the application's endpoints (URL, enabled state, filtered event types).      |
| `get_endpoint`              | Full configuration of one endpoint.                                              |
| `get_endpoint_stats`        | Success / fail / pending / sending counts over a time window.                    |
| `get_transformation`        | An endpoint's transformation code, enabled state, and variables.                  |
| `update_transformation`     | Set an endpoint's transformation code and/or toggle it on or off.                 |
| `list_messages`             | List messages sent to the application (filter by event type, channel, time).      |
| `list_attempts_by_endpoint` | Delivery attempts for an endpoint (e.g. only failures), with response bodies.     |
| `list_attempts_by_message`  | Every endpoint a single message was attempted against, and how each responded.    |
| `get_message`               | A message's event type, channels, and JSON payload.                              |
| `get_attempt`               | One attempt in full, including the response status code and body.                 |
| `resend_message`            | Resend one message to an endpoint.                                               |
| `recover_endpoint`          | Replay all failed messages for an endpoint since a given date.                    |

Most of these are read-only. Three of them are not: `resend_message` and `recover_endpoint` perform real deliveries, and `update_transformation` changes live endpoint configuration. The server instructs agents to only use them when explicitly asked, and most agents will ask for confirmation before running a tool, but as with any agent, your users should review those calls before approving them.

Some questions this makes easy to answer:

- "Why is the `invoice.paid` event failing?": the agent searches the correct endpoint, checks the endpoint's delivery stats, then the failed attempts and the exact response your handler returned.
- "What does the payload for this event actually look like?": the agent fetches a recent message and its JSON payload
- "My handler was down for an hour, can you replay what it missed?": the agent recovers the endpoint from that point in time.

## Tokens and security

The server is scoped to **a single application**: the token your user generates from the App Portal encodes the application it belongs to, so an agent can only ever see that one customer's data, which is the same data the App Portal itself shows them.

MCP tokens are application-scoped and restricted: they can read the application, its endpoints, event types, integrations, messages, and attempts, and they can update endpoint transformations and create messages and attempts (what powers resend and recover). They cannot touch anything outside the application they were issued for, and they cannot be used as a Svix API key for your organization.

A few things worth passing on to your users:

- **Tokens expire.** By default they're valid for 7 days, after which the agent needs a new one generated from the App Portal.
- **Tokens can be revoked at any time.** From the **MCP** tab, the token's menu -> **Expire** revokes it immediately, and any agent using it loses access.
- **Payload data reaches the agent's model.** Message payloads the agent reads are sent to whichever model provider backs the coding agent, so treat this the same way you'd treat pasting a payload into that tool.

Turning off **Enable App Portal MCP** in your Dashboard settings hides the MCP tab, so your users can no longer generate new tokens. Tokens that were already issued keep working until they expire, so revoke any you don't want to remain active.


<!-- Source: https://docs.svix.com/api-keys -->

# API keys

Manage your API keys to authenticate requests with Svix.
Svix authenticates your API requests using your account’s API keys. If you don’t include your key when making an API request, or use an incorrect or outdated one, Svix returns an error.

**API keys are per environment.** Every organization starts with a development environment with a corresponding API key. This key should only be used for development or internal testing and is not intended to be used in any production systems.

## Obtaining your API keys

Your API keys can be found on the "API Access" page of the Svix Dashboard.

![API Access page](/img/api-access-page.png)

## Keeping your keys safe

Your secret API key can be used to make any API call on behalf of your account. Treat your secret API key as you would any other password. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using. Control access to your key using a password manager or secrets management service.

## Rotating keys

Svix support creating multiple API keys per environment. This gives you a lot of flexibility when rotating keys. For example, you can create a new key, replace all instances of the old key, and then expire the old key for a zero downtime key rotation.

When expiring keys, you can also define when you would like the key to expire. Either immediately, or at a later point in time.


<!-- Source: https://docs.svix.com/app-portal -->

---
title: Consumer App Portal
---
# Consumer App Portal

Svix comes with a consumer application portal for your users (webhook consumers) that you can use out of the box. Your users can then use it to add endpoints, debug delivery, as well as inspect and replay past webhooks. This is the easiest way to get started, but you can alternatively use the API to build your own.

If you're looking for a live instance of the app portal, you can find one here: https://example.svix.com/

Here is what it looks like standalone, or scroll down for the embedded version:

![App Portal screenshot](/img/app-portal/endpoint.png)

## Application portal usage guides

For more information on how to use the app portal please refer to the [receiving webhooks](./receiving/introduction.mdx) section of the docs.

## Giving your users access

<Callout type="default">

App portal access is based on short-lived sessions using special magic links. You customers don't need a Svix account, and they don't even need to know that Svix exists.

</Callout>
To give your users access to the App Portal, just use the [app portal access endpoint](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access). Calling this endpoint with an `app_id` returns a single-use URL you can just redirect your users to in order to log them into the App Portal. They will stay logged in for a few days or until they log out.

The following API call to get the URL should be called from the backend as the Svix API key should not be shared with the frontend. The values returned from this API call (URL and token) are safe to pass to the frontend.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
const svix = new Svix("AUTH_TOKEN");
const dashboard = await svix.authentication.appPortalAccess("app_Xzx8bQeOB1D1XEYmAJaRGoj0", {});
// A URL that automatically logs user into the dashboard
console.log(dashboard.url);
```

</TabItem>
<TabItem value="Python">

```python
svix = Svix("AUTH_TOKEN")
dashboard = svix.authentication.app_portal_access("app_Xzx8bQeOB1D1XEYmAJaRGoj0", AppPortalAccessIn())
# A URL that automatically logs user into the dashboard
print(dashboard.url)
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let dashboard = svix
    .authentication()
    .app_portal_access(
        "app_Xzx8bQeOB1D1XEYmAJaRGoj0".to_string(),
        AppPortalAccessIn::default(),
        None,
    )
    .await?;
// A URL that automatically logs user into the dashboard
println!("{}", dashboard.url);
```

</TabItem>
<TabItem value="Go">

```go
svixClient := svix.New("AUTH_TOKEN", nil)
dashboard, _ := svixClient.Authentication.AppPortalAccess(ctx, "app_Xzx8bQeOB1D1XEYmAJaRGoj0", &svix.AppPortalAccessIn{})
// A URL that automatically logs user into the dashboard
fmt.Println(dashboard.Url)
```

</TabItem>
<TabItem value="Java">

```java
Svix svix = new Svix("AUTH_TOKEN");
AppPortalAccessOut dashboard = svix.getAuthentication().appPortalAccess("app_Xzx8bQeOB1D1XEYmAJaRGoj0", new AppPortalAccessIn());
// A URL that automatically logs user into the dashboard
System.out.println(dashboard.getUrl());
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val svix = Svix("AUTH_TOKEN")
val dashboard = svix.authentication.appPortalAccess("app_Xzx8bQeOB1D1XEYmAJaRGoj0", AppPortalAccessIn())
// A URL that automatically logs user into the dashboard
println(dashboard.url)
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
dashboard = svix.authentication.app_portal_access("app_Xzx8bQeOB1D1XEYmAJaRGoj0", Svix::AppPortalAccessIn.new({}))
# A URL that automatically logs user into the dashboard
puts dashboard.url
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
var dashboard = await svix.Authentication.AppPortalAccessAsync("app_Xzx8bQeOB1D1XEYmAJaRGoj0", new AppPortalAccessIn{});
// A URL that automatically logs user into the dashboard
Console.WriteLine(dashboard.Url)
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$dashboard = $svix->authentication->appPortalAccess(
  'app_Xzx8bQeOB1D1XEYmAJaRGoj0',
  AppPortalAccessIn::create()
);

echo $dashboard->url . PHP_EOL;
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN="AUTH_TOKEN"
svix authentication app-portal app_Xzx8bQeOB1D1XEYmAJaRGoj0
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X POST "https://api.us.svix.com/api/v1/auth/app-portal-access/app_Xzx8bQeOB1D1XEYmAJaRGoj0/" \
    -H  "Accept: application/json" \
    -H  "Authorization:  Bearer AUTH_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{}'
```

</TabItem>
</CodeTabs>

In most cases you would want to create an API endpoint on your end that your frontend can call to get the URL. For example, your code may look something like this:

```javascript
const svix = new Svix("AUTH_TOKEN");

// API path: /webhooks/app-portal
function get_app_portal(authenticated_user) {
  const svix_app_id_or_uid = authenticated_user.id;
  return await svix.authentication.appPortalAccess(svix_app_id_or_uid, {});
}
```

Then your frontend will do something like this:

```javascript
// React example

function AppPortal() {
  const [appPortal, setAppPortal] = React.useState(null);

  React.useEffect(() => {
    fetch('https://api.your-backend.com/webhooks/app-portal', { method: "POST" })
    .then((res) => res.json())
    .then((result) => setAppPortal(result));
  }, []);

  const url = appPortal?.url;
  if (url) {
    // NOTE: in practice you'd want to use the svix-react library
    return (
      <iframe
        src={url}
        style="width: 100%; height: 100%; border: none;"
        allow="clipboard-write"
        loading="lazy"
      >
      </iframe>
    );
  else {
    return <div>Loading...</div>;
  }
};
```

### Showing a specific page

If you want your users to be redirected to a specific page of the App Portal, you can add a `next` query parameter to the URL:

```
https://app.svix.com/login?next=/endpoints/abc#key=xyz
```

You should use a URL parsing library to add the query parameter (avoid editing the URL manually).

### Feature flags

When [creating an App Portal URL](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access), you can optionally specify a list of feature flags (using the `featureFlags: [ ... ]` field) to restrict which event types your users will see in the Event Catalog and the API.

To learn more refer to the [Event Types](./event-types.mdx#event-type-feature-flags) documentation.

### Session IDs

App Portal URLs can also be generated with a specific session ID, using the `sessionId` field. App Portal URLs created with a session ID can be selectively invalidated by the [Expire All](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.expire-all) endpoint by including the session ID in the Expire All request.

Multiple App Portal URLs can be created with the same session ID, and if [Expire All](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.expire-all) is called with a session ID, only App Portal URLs with that specific session ID will be invalidated.

## Embedding in your own dashboard

### Embedding as an iframe

The returned URL from the previous section can also be embedded in your own dashboard using an iframe.

![Embedded App Portal screenshot](/img/app-portal/embedded.png)

To add this to your application, just pass the URL you received in the previous example to the `src` property of the iframe:

```html
<iframe
  src="http://app.svix.com/login#key=eyJhcHBJZCI6ICJhcHBfMXRSdFlMN3pwWWR2NHFuWTRRZFI1azE4eXQ0IiwgInRva2VuIjogImFwcHNrX2UxOUN0Rm5hbTFoOU1Gamh5azRSMTUzNUNSd05VSWI0In0="
  style="width: 100%; height: 100%; border: none;"
  allow="clipboard-write"
  loading="lazy"
>
</iframe>
```

We have also included some basic styling to make the iframe to look nicer, though that can be omitted or modified depending on your needs.

**Important**: the `allow` directive above is required for clipboard actions to work, though they may still fail if you've blocked them with the [Permissions Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) header.

### Embedding in a React application

We also provide the [`svix-react`](https://www.npmjs.com/package/svix-react) package that you can use to easily embed the App Portal. To use it, simply run:

```sh
npm install svix-react
# or
yarn add svix-react
```

The npm package is lightweight and provides some basic styling and a loading indicator out of the box. To use it, simply provide the magic link from the [`app_portal_access` endpoint](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access).

```js
import React from "react";
import ReactDOM from "react-dom";
import { AppPortal } from "svix-react";

import "svix-react/style.css";

const SvixEmbed = () => {
  const [appPortal, setAppPortal] = React.useState(null);

  React.useEffect(() => {
    // Prerequisite: You'll need an endpoint that returns the App Portal
    // magic URL (https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access)
    fetch(`/your-backend-service/svix/app-portal`, { method: "POST" })
      .then((res) => res.json())
      .then((result) => setAppPortal(result));
  }, []);

  return <AppPortal url={appPortal?.url} />;
};

const App = () => <SvixEmbed />;

ReactDOM.render(<App />, document.body);
```

You can optionally use the `fullSize` prop (`<AppPortal fullSize />`) so that App Portal will automatically grow to fit its contents.

### Example integration

The [`svix-example`](https://github.com/svix/svix-example) repo contains an example implementation of the App Portal in a React application, using NextJS. In the webhooks Dashboard [page](https://github.com/svix/svix-example/blob/main/src/pages/dashboard/webhooks.tsx), you can see how to get the App Portal login URL and use it to render the App Portal in an iframe.

### Design Considerations

When embedding the App Portal into your application, keep in mind that the App Portal is an information dense master-detail view. We recommend keeping the view at 100% width to avoid abbreviating important information for your users. If you are hoping to avoid having an embedded scrollbar, we recommend putting the view inside a full screen modal from your dashboard, or using the `fullSize` prop so that the App Portal sizes itself based on its content.

![embedded iframe screen](/img/app-portal/embedded-view-screen.png)

## White labeling

Keep the same look and feel of your application by white labeling the App Portal. From the [Svix dashboard](https://dashboard.svix.com/settings), you can configure the color palette, font and the logo that your users will see.

To customize these settings, please head to your [Organization Settings](https://dashboard.svix.com/settings) on the Svix Dashboard.

### Custom settings per application

In some scenarios, you may want to customize the application portal per application, rather than for your whole organization. For example, if you change the color of your own dashboard for each of your users.

This is possible by changing the query parameters of the URL to the settings of your choosing.

<Callout type="error">

Please use proper URL parsing rather than string manipulation as the structure of the URL (e.g. the fragment part) may change. Another reason to use proper URL parsing is that you want to make sure to URL-encode the parameters.

</Callout>
The supported parameters are:

- `primaryColorLight` and `primaryColorDark` - the primary color of the UI in light and dark mode, respectively. Format: `RRGGBB`, e.g. `28bb93`.
- `icon` - a URL to an image file. E.g. `https://www.example.com/logo.png` (remember to URL-encode it!).
- `fontFamily` - one of the fonts listed in the dashboard (see previous section). E.g. `Roboto`.
- `darkMode (false|true|auto)` - when set to `true`, dark mode will be turned on by default when the app portal is opened. `auto` will use the user's system preferred color mode. Defaults to `false`.
- `hideNavigation` - when set to `true`, the navigation tabs will be hidden. This can be useful to embed only specific sections of the app portal, in combination with the `next` parameter (see [Showing a specific page](#showing-a-specific-page)).
- `noGutters` - when set to `true`, the app portal will not have any left or right padding within the iframe. This can be useful to align the app portal content with other elements in your site.

So for example:

```
http://app.svix.com/login?primaryColorLight=22cc91&primaryColorDark=28bb93&darkMode=true&fontFamily=Roboto#key=eyJhcHBJZCI6ICJhcHBfMXRSdFlMN3pwWWR2NHFuWTRRZFI1azE4eXQ0IiwgInRva2VuIjogImFwcHNrX2UxOUN0Rm5hbTFoOU1Gamh5azRSMTUzNUNSd05VSWI0In0=
```

## App Portal capabilities

App portal capabilities let you disable certain functionality when giving your customers access to the app portal.
You can control the exact list of capabilities by using the `capabilities` property when calling [the app portal access API endpoint](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access).

To give your customer read-only access to the app portal, you can use the `ViewBase` capabilities. For the full list of `capabilities`, please refer to [the app portal access API docs](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access).

## Implementing your own Consumer App Portal functionality

You can implement Consumer App Portal functionality into your own dashboard using ergonomic React Hooks provided by the [`svix-react`] library or using the [Svix JavaScript library](https://api.svix.com/docs).

This approach allows you to use your own UI structure and components and have full control over the behavior. It's also very common to mix-and-match your own app portal with the embedded consumer app portal that we provide as an iframe. For example, you can build the list, create, and edit endpoint views yourself, and then offer the full app portal in "read only" mode to give your customers access to the more advanced functionality available in the app portal.

### Authentication

Whether implementing your own dashboard using the Svix React library or the JavaScript library, you can use the Svix frontend-friendly tokens. These are tokens that can be safely passed to the frontend as they expire automatically and are scoped to the respective application. These are the same kinds of tokens used by the iframe.

To get a frontend-friendly token, call the [get consumer app portal access API](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access) from the backend and pass the returned token to the frontend.

This token will be scoped to the specific application, will expire automatically based on the set expiry, and will only have the capabilities associated with it on creation.

### Svix React example

The hooks are an abstraction over the `svix` JavaScript library and help to handle concerns like paginating over large lists of data, and reloading data.

Using the hooks requires wrapping your application or components in `<SvixProvider>`:

```jsx
import { SvixProvider } from 'svix-react'

export default function App() {
  return (
    <SvixProvider token={token} appId={appId}>
      {/** your app's components **/}
    </SvixProvider>
  )
}
```

Then, you can use hooks like `useEndpoints`:

```jsx
import { useEndpoints } from 'svix-react'

export default function ListEndpoints() {
  const endpoints = useEndpoints()

  return (
    <div>
      {endpoints.error && <div>An error has occurred</div>}
      {endpoints.loading && <div>Loading...</div>}
      <ul>
        {endpoints.data?.map((endpoint) => (
          <li>{endpoint.url}</li>
        ))}
      </ul>
      <button disabled={!endpoints.hasPrevPage} onClick={endpoints.prevPage}>
        Previous Page
      </button>
      <button disabled={!endpoints.hasNextPage} onClick={endpoints.nextPage}>
        Next Page
      </button>
    </div>
  )
}
```

## FAQ

### Can I inject my own CSS in the embedded app portal?

We don't support injecting custom CSS into the pre-built embedded app portal as it would make the integration very fragile. CSS is very powerful, which means people injecting CSS would be able to make significant changes that we won't be able to test and will likely cause the UI to break.

With that being said, there are two alternatives:

1. We support a set of white-labeling customizations, and are always happy to add more. Please reach out with your suggest customization.
2. You can refer to the [implementing your own consumer app portal](#implementing-your-own-consumer-app-portal-functionality) section above which will enable you to build a fully custom UI.


[`svix-react`]: https://www.npmjs.com/package/svix-react


<!-- Source: https://docs.svix.com/app-portal/oss -->

---
title: Consumer App Portal (OSS)
---
# Consumer App Portal (OSS)


The [Consumer Application Portal](/app-portal) is currently only included in the [hosted version of Svix](https://www.svix.com) and not in the open source version.
This is probably going to change in the future, but for now you can just build your own.

Fortunately, building your own is fairly simple using [`svix-react`] if you use React,
or directly with the [JavaScript / TypeScript SDK](https://www.npmjs.com/package/svix) otherwise.

Using the `svix-react` hooks requires wrapping your application or components in `<SvixProvider>`:

```jsx
import { SvixProvider } from 'svix-react'

export default function App() {
  return (
    <SvixProvider token={token} appId={appId}>
      {/** your app's components **/}
    </SvixProvider>
  )
}
```

Then, you can use hooks like `useEndpoints`:

```jsx
import { useEndpoints } from 'svix-react'

export default function ListEndpoints() {
  const endpoints = useEndpoints()

  return (
    <div>
      {endpoints.error && <div>An error has occurred</div>}
      {endpoints.loading && <div>Loading...</div>}
      <ul>
        {endpoints.data?.map((endpoint) => (
          <li>{endpoint.url}</li>
        ))}
      </ul>
      <button disabled={!endpoints.hasPrevPage} onClick={endpoints.prevPage}>
        Previous Page
      </button>
      <button disabled={!endpoints.hasNextPage} onClick={endpoints.nextPage}>
        Next Page
      </button>
    </div>
  )
}
```

[`svix-react`]: https://www.npmjs.com/package/svix-react


<!-- Source: https://docs.svix.com/channels -->

---
title: Channels
---
# Channels

Channels are an extra dimension of filtering messages that is orthogonal to [event types](./event-types.mdx). You can listen to multiple channels from each endpoint, and you can send each message to multiple channels.

Event types imply a specific consistent schema, and mean a specific type of message. Channels are filters based on the expected recipient or group of recipients.

**Note:** like event types, channels are meant to filter messages to a particular application, and not across applications.

## How to use it

You first need to enable support to it for each of your environments from [the dashboard](https://dashboard.svix.com/settings/organization/general-settings).

Once enabled, your customers can choose their wanted channels from the Application Portal, or alternatively you can set it per endpoint in the API.

![Add endpoint with channels](/img/channels.png)

You then need to send messages with the corresponding channels in order for these to reach the endpoints that filter by them. See below for the channels filtering rules.

```typescript
await svix.message.create('app_id', {
    eventType: "user.signup",
    channels: [
        "project_123",
        "project_group_11"
    ],
    payload: {
        "username": "test_user",
        "email": "test@example.com"
    },
});
```

## When not to use it

The channels are not meant as a way to filter messages across different customers, that's what applications are for. Applications provide proper isolation between messages of different customers, while channels do not. Additionally, while you can have an infinite number of applications, there's a limit to the number of endpoints per application (more on that [on the Endpoint API docs](https://api.svix.com/docs#tag/Endpoint)).

Additionally, there are limits to the number of channels messages and endpoints can be associated with. And having applications with a large number of endpoints is very inefficient and can hurt performance.

## Example use-cases

Channels are useful for when you have a variety of sub-categories or recipients that expect the same types of messages but just need additional filtering.

For example, consider Github. You may want to define webhooks for the whole organization, but only send certain events to certain endpoints based on the repository. You could just create a Svix App per repository and then manually add the endpoints to each, but it makes for a much better experience to have the webhook handling defined in one place with the same endpoints listening to multiple projects.

So for example, you can have `svix`, `svix/svix-webhooks` and `svix/svix-docs` as channels, and then have Github send messages for both `svix` and for each repo whenever an event occurs on a specific repository. Github's customers can then create endpoints that listen to events either for the whole group, or for each repository in particular.

## Channels filtering rules

Channels are case-sensitive, and endpoints that are filtering for specific channels will only get messages sent to that specific channel.

Svix will send (or not send) to endpoints based on the following conditions:
1. Endpoint has no channels set: this is a catch-all, all messages are sent to to it, regardless of whether the message had channels set.
2. Both endpoint and message have channels set: if there's a shared channel between them, the message will be sent to the endpoint.
3. Endpoint has channels set and message has *no* channels set: the message will not be sent to the endpoint.


<!-- Source: https://docs.svix.com/common-usage-examples -->

---
title: Common Usage Examples
---
# Common Usage Examples

This document includes examples and useful information for how to model your use-case with Svix.

This list is not exhaustive and only covers some of the more common examples. Svix is used by a variety of different customers for a variety of different use-cases. If your use-case doesn't fit any of the below, please [contact us](/get-help/) and we would be happy to chat on how to best use Svix in your particular circumstances.

<AgentSkillsCallout />

## Preamble

While different use-cases often require different solutions, there are a few Svix features that are useful in most use-cases and we will highlight them in this section.

### Consumer Application and Endpoint UIDs, and message event IDs

Svix enables you to use your internal `ID`s as ids for Svix entities by using the `UID` property of consumer applications and endpoints, and `eventId` of messages.

This lets you use Svix in a completely stateless manner, without having to store the Svix identifiers (or anything) in your own database.

For more information, please refer to the [section about `UID`s in the overview](./overview.mdx#ids-and-uids).


### Event types

Each message sent through Svix has an associated [event type](./event-types.mdx). Event types are identifiers denoting the type of message being sent and are the primary way for webhook consumers to configure what events they are interested in receiving.

You can even automatically generate public documentation for your webhooks [by making your event catalog public](./event-types.mdx#publishing-your-event-catalog).


### Consumer Application portal

Svix comes with an application portal for your users that you can use out of the box. Your users can then use it to add endpoints, debug delivery, as well as inspect and replay past webhooks. The application portal can be used as a standalone page, or embedded in your own dashboard using an iframe.

Most Svix customers use it in an iframe, or implement it themselves (either fully or partially) using the Svix API.

For more information, please refer to the [app portal section of the docs](./app-portal.mdx).


### Idempotency

Svix supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

For more information, please refer to the [idempotency section of the docs](./idempotency.mdx).


### Webhooks sent by Svix

As you may expect from a webhooks service, Svix also uses webhooks to notify you of events. For example, Svix will send you a webhook when a message delivery has failed, or an endpoint has been failing for too long of a period.

For more information, please refer to the [operational webhooks section of the docs](./incoming-webhooks.mdx).


### Environments (sub-accounts)

Svix supports having multiple environments (sub-accounts) within the same Svix account. One common use-case is to separate production, staging and development environments. Another one, is ensuring data stays in a specific geography (e.g. the EU) for compliance reasons.

For more information, please refer to the [managing environments section of the docs](./account/environments.mdx).


## Example use-cases

### The common use-case (probably you)

#### Who is it for

This use-case is the right one if you have different customers on your service, and each of them gets sent webhooks independently based on activities on their own separate accounts. This is the most common use-case and probably matches most people.

One company that matches this description is Stripe. Every Stripe customer has their own account, and webhooks are sent by Stripe to a specific account. The webhooks may cover the activities of many of a particular Stripe customer's users (e.g. whether they paid), but webhooks sent by Stripe only ever affect one customer.

Another example is [Clerk](https://clerk.dev). Each of Clerk's customers may subscribe to webhooks related to the activity of its own account only.


#### Usage example

A service matching this description should create one application for each one of its customers. The service will then send events related to this specific customer to the application, and offer the [application portal](./app-portal.mdx) to each of its customers so that customers can manage their own webhooks.

As mentioned above, the service can utilize event types to let its customers filter which event they would like to listen to, and it can also utilize application `UID`s to [use Svix in a fully stateless manner](./overview.mdx#ids-and-uids).


### Multiple channels use-case

#### Who is it for

This use-case is similar to the common one, but with one small difference: your customers may take part in completely separate activities or projects.

One common example for this is project management software such as Github, Jira, and Linear. Github users may be watching multiple repositories and be a member of multiple organizations. Their customers want to be able to choose which webhooks should get to which endpoints based on the project or organization.

#### Usage example

One easy solution is to use a different application for each project. While it's possible to do it this way, it does pose a few limitations. First of all, the app portal only shows one application at a time, so managing endpoints across different applications is difficult. But also, oftentimes you'd like to listen for events affecting multiple projects from the same endpoint, which is very cumbersome if you've created multiple applications.

Enter [channels](./channels.mdx). Channels are an extra dimension of filtering messages that is similar, but orthogonal to event types. Channels let you include in the message which channels have been affected by a particular change. For example, you can send a message and mark it as affecting `proj_12` and `proj_35`. Endpoints can then be marked as listening to only changes affecting particular projects (channels) and the messages will be filtered accordingly.

Services matching this use-case often implement their own UI for adding and editing endpoints instead of using the application portal, in order to build a nice UI for auto completing, and choosing relevant channels. They would still use the application portal for offering their customers a way to gain visibility into the webhooks being sent, just in read-only mode.


### Partners use-case

#### Who is it for

This use-case is for services where the webhooks are not being ingested by the service's customers, but rather by partners that, for example, build extensions for the service.

Let's take Zoom for example. They have an application marketplace, and you can install different applications on your Zoom account. As a Zoom customer, you are not actually listening to webhooks yourself, but Zoom needs to send them to the applications you've installed.

#### Usage example

There are multiple ways to achieve this, but the recommended method is to have one application per partner. When an event is triggered for a customer that a partner is interested in, a message is sent to this partner's app (as well as those for any other partners listening).

Let's take a look at a concrete example: let's assume we have a customer that has enabled multiple partners on their account (e.g. installed those apps). Your system knows which partners are enabled for that specific customer (as they enabled them on your system in the first place), for simplicity, let's assume you can get that list by calling `list_enabled_partners()`.

Then, whenever an event happens on your end for a specific customer, you can get the list of enabled partners and send all of them messages one-by-one, similar to the following pseudo-code:

```python
# Some event was triggered on your system for a customer

# Send a message to the relevant customer
svix.message.create(customer.id, {...})

# Get the list of all of the enabled partners for this customer
enabled_partners = customer.list_enabled_partners()

# Send a message for each enabled partner
for partner in enabled_partners:
    svix.message.create(partner.id, {...})
```


### The mix and match use-case

#### Who is it for

Some services have more complex use-cases that match more than one of the above examples. For example, your service may have both partners and end-users, and both may need to be able to listen to webhooks. Or maybe even two types of customers listening to the same events (so essentially "using" the common scenario twice).

One such example is Gmail, where the user may want to connect third party add-ons (e.g. a CRM) and listen to a webhook themselves.

#### Usage example

One easy solution is to just have the equivalent of multiple use-cases layered on top of one another, i.e., send messages to multiple applications that are exposed differently in your service's dashboard to different partners and customers based on their roles.


### Other use-cases

As mentioned above, this list is not exhaustive and only covers some of the more common examples. Svix is used by a variety of customers for a variety of use-cases. If your use-case doesn't fit any of the above, please [contact us](/get-help/) and we would be happy to chat on how to best use Svix in your particular circumstances.


<!-- Source: https://docs.svix.com/connectors/custom-connector -->

---
title: Custom Connector
---
# Custom Connector


If you don't find a built-in integration for the service you want to connect to, you can create a Custom Connector.

![Custom Connector in the App Portal](/img/connectors/custom-connector-dropdown.png)

## Configuration

You can provide your own integration name and icon, and write instructions for your users on how to use it (in addition to the [default transformation code](/connectors/#how-to-use-connectors) like in any other connector).

![Custom Connector](/img/connectors/custom-connector-form.png)

You can also (optionally) configure a default endpoint URL and a default authentication method for custom connectors. This will prefill certain fields in the app portal for your customers, to make it easier for them to use the connector.

![Custom Connector Authentication Configuration](/img/connectors/custom-connector-form-auth.png)

The supported authentication methods are `HttpBasic` and `HttpBearer`.

When using `HttpBasic`, the App Portal will display a `username` and `password` input field, and add the `Authorization: Basic base64(<username>:<password>)` header to the endpoint (see [RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617)) .

When using `HttpBearer`, the App Portal will display a `token` input field, and add the `Authorization: Bearer <token>` header to the endpoint (see [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)).

![Custom Connector Authentication](/img/connectors/custom-connector-auth.png)


<!-- Source: https://docs.svix.com/connectors -->

---
title: Connectors Endpoints
asIndexPage: true
---

# Connectors Endpoints

Connectors is a Svix feature that lets you provide your customers with pre-made integrations to connect your webhooks to other services.

## How to use Connectors

Connectors are enabled when [enabling transformations](/transformations#enabling-transformations). After enabling Transformations, you will see a new dashboard section where you will be able to create new connectors.

![Connectors list](/img/connectors-list.png)

To configure a connector, you need to provide the following details:

- `Type`: Choose from a set of services that provide easy webhook integrations, or choose `Custom` to build your own integration. We currently support Slack, Discord, and many more services, listed below.
- `Description`: Describe the integration to your customers.
- `Event Types`: Specify which events are going to be supported out-of-the-box by the integration.
- `Transformation Code`: This is the glue code that will turn incoming webhook events into useful payloads for your integration. For example, if you are building a connector that sends Slack messages
every time a new invoice is created, the transformation will read `invoice.created` events and return a payload that works for Slack, like:
```js
webhook.payload = { "text": `An invoice of $${webhook.payload.amount} has been created.` }
```

The transformation code needs to account for all event types you choose to support. You can define different behaviors for each event type by switching on the `webhook.eventType` field.

For example, this transformation will create a different message depending on if the event type is `invoice.created` or `invoice.deleted`:

```js
/**
 * @param webhook the webhook object
 * @param webhook.method destination method. Allowed values: "POST", "PUT", "PATCH"
 * @param webhook.url current destination address
 * @param webhook.eventType current webhook Event Type
 * @param webhook.payload JSON payload
 * @param webhook.cancel whether to cancel dispatch of the given webhook
 */
function handler(webhook) {
  switch (webhook.eventType) {
    case "invoice.created":
      webhook.payload = {
        text: `${webhook.payload.name} created an invoice for $${webhook.payload.amount}`
      };
      break;
    case "invoice.deleted":
      webhook.payload = {
        text: `${webhook.payload.name} deleted an invoice`
      };
      break;
  }

  return webhook
}
```

Your customers will be able to customize the transformation code and the event types they listen to. Your definition should act as a working starting point they can use.


## Connectors in the App Portal

After creating at least one connector, your customers will be able to choose it when creating an endpoint.

![Adding an Endpoint using a Connector](/img/connectors-endpoint.png)

## Connection types

### <ConnectorLogo name="slack" /> Slack [#slack]

The Slack built-in integration lets you send messages to Slack channels via webhooks. It shows a 'Connect to Slack' button that lets your users get a Slack incoming webhook URL using OAuth in a few clicks, without leaving your site.

![Connect to Slack](/img/connectors/connect-to-slack.png)

The transformation code should format the webhook payload according to [Slack's Incoming Webhook API](https://api.slack.com/messaging/webhooks#posting_with_webhooks).

Here's an example transformation:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   amount: 99.99,
   *   customer_name: "John Doe",
   *   invoice_id: "inv_123"
   * }
   *
   * See https://api.slack.com/messaging/webhooks#posting_with_webhooks
   */
  webhook.payload = {
    text: `💰 New invoice for $${webhook.payload.amount} from ${webhook.payload.customer_name}`
  };

  return webhook;
}
```


### <ConnectorLogo name="discord" /> Discord [#discord]

The Discord built-in integration lets you send messages to Discord channels via webhooks. It shows a 'Connect to Discord' button that lets your users get a Discord incoming webhook URL using OAuth in a few clicks, without leaving your site.

![Connect to Discord](/img/connectors/connect-to-discord.png)

The transformation code should format the webhook payload according to [Discord's Execute Webhook API](https://discord.com/developers/docs/resources/webhook#execute-webhook).

Here's an example transformation:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     email: "john@example.com",
   *     name: "John Doe"
   *   },
   *   cancellation_reason: "Too expensive"
   * }
   *
   * See https://discord.com/developers/docs/resources/webhook#execute-webhook
   */
  webhook.payload = {
    embeds: [{
      title: "❌ Subscription Cancelled",
      description: `User ${webhook.payload.user.email} cancelled their subscription`,
      color: 0xff0000
    }]
  };

  return webhook;
}
```

### <ConnectorLogo name="microsoft-teams" /> Microsoft Teams [#teams]

The Microsoft Teams integration will show your users instructions on how to get a Teams webhook URL.

The transformation code should format the webhook payload according to [Microsoft Teams' Incoming Webhook API](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?#send-adaptive-cards-using-an-incoming-webhook).

![Connect to Microsoft Teams](/img/connectors/connect-to-teams.png)

Here's an example transformation for a support ticket created event:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   ticket_id: "TICKET-123",
   *   customer_name: "John Doe",
   *   priority: "high",
   *   description: "Can't access my account"
   * }
   *
   * See https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?#send-adaptive-cards-using-an-incoming-webhook
   */
  webhook.payload = {
    type: "message",
    attachments: [{
      contentType: "application/vnd.microsoft.card.adaptive",
      content: {
        type: "AdaptiveCard",
        body: [
          {
            type: "TextBlock",
            text: "🆘 New Support Ticket",
            weight: "Bolder"
          },
          {
            type: "TextBlock",
            text: `Ticket #${webhook.payload.ticket_id} from ${webhook.payload.customer_name}`
          }
        ]
      }
    }]
  };

  return webhook;
}
```

### <ConnectorLogo name="hubspot" id="hubspot" /> Hubspot [#hubspot]

The Hubspot integration lets you connect webhooks directly to the [Hubspot API](https://developers.hubspot.com/docs/api/overview). It shows a 'Connect to Hubspot' button that lets your users get a Hubspot access token that can be used to connect to the Hubspot API.

The integration will request access to the following [OAuth scopes](https://developers.hubspot.com/docs/api/working-with-oauth) in the [Hubspot API](https://developers.hubspot.com/docs/api/overview):

- `crm.objects.contacts.write`
- `crm.objects.companies.write`
- `crm.objects.deals.write`
- `crm.objects.quotes.write`
- `crm.objects.marketing_events.write`

![Connect to Hubspot](/img/connectors/connect-to-hubspot.png)

The transformation code should set the webhook URL to the Hubspot API endpoint (depending on the object) and format the payload appropriately to create the object in Hubspot.

For example, if you send a `user.created` webhook, and want to write a connector that creates a contact in Hubspot, the transformation code could look like this:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     firstname: 'John',
   *     lastname: 'Doe',
   *     email: 'john.doe@example.com'
   *   }
   * }
   */
  webhook.url = "https://api.hubapi.com/crm/v3/objects/contacts"; // The method is already POST
  webhook.payload = {
    properties: {
      email: webhook.payload.email,
      firstname: webhook.payload.user.firstname,
      lastname: webhook.payload.user.lastname,
    }
  };

  return webhook
}
```

### <ConnectorLogo name="closecrm" /> Close CRM [#closecrm]

The Close CRM connector lets your users connect their webhooks to the Close CRM API. Users enter their Close CRM API key in the [App Portal](/app-portal).

This example uses [Close CRM's Contact API](https://developer.close.com/resources/contacts/), formatting the payload to create a contact in Close CRM:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     email: "john@example.com",
   *     name: "John Doe",
   *     phone: "+1234567890"
   *   }
   * }
   *
   * See https://developer.close.com/resources/contacts/
   */
  webhook.url = "https://api.close.com/api/v1/contact/";
  webhook.payload = {
    lead_id:"lead_QyNaWw4fdSwxl5Mc5daMFf3Y27PpIcH0awPbC9l7uyo",
    name: webhook.payload.user.name,
    emails: [webhook.payload.user.email],
    phones: [webhook.payload.user.phone]
  };

  return webhook;
}
```

### <ConnectorLogo name="segment" /> Segment [#segment]

The Segment connector lets your users send events to Segment's API. Users enter their Segment Write Key in the [App Portal](/app-portal).

This example uses [Segment's Track API](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/#track), formatting the payload appropriately:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     id: "user123",
   *     email: "john@example.com",
   *     name: "John Doe"
   *   },
   *   event: "subscription_created",
   *   properties: {
   *     plan: "premium",
   *     price: 99.99
   *   }
   * }
   *
   * See https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/#track
   */
  webhook.url = "https://api.segment.io/v1/track";
  webhook.payload = {
    userId: webhook.payload.user.id,
    event: webhook.payload.event,
    properties: {
      ...webhook.payload.properties,
      email: webhook.payload.user.email,
      name: webhook.payload.user.name
    },
    timestamp: new Date().toISOString()
  };

  return webhook;
}
```

### <ConnectorLogo name="customerio" id="customerio" /> Customer.io [#customerio]

The Customer.io connector lets your users send events to Customer.io's Track API. Users enter their Customer.io Site ID and API Key in the [App Portal](/app-portal).

This example uses [Customer.io's Track API](https://docs.customer.io/integrations/api/track/), formatting the payload appropriately:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     id: "user123",
   *     email: "john@example.com",
   *     name: "John Doe"
   *   },
   *   event: "subscription_created",
   *   properties: {
   *     plan: "premium",
   *     price: 99.99
   *   }
   * }
   *
   * See https://docs.customer.io/integrations/api/track/
   */
  webhook.url = "https://track.customer.io/api/v2/entity";
  webhook.payload = {
    type: "person",
    identifiers: {
      id: webhook.payload.user.id
    },
    action: webhook.payload.event,
    name: webhook.payload.event,
    attributes: {
      ...webhook.payload.properties,
      email: webhook.payload.user.email,
      name: webhook.payload.user.name
    }
  };

  return webhook;
}
```

### <ConnectorLogo name="sendgrid" id="sendgrid" /> Sendgrid [#sendgrid]

The SendGrid connector lets your users send events as emails using SendGrid. Users enter their SendGrid API key in the [App Portal](/app-portal).

The transformation code should format the webhook payload according to [SendGrid's Mail Send API](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send).

Here's an example transformation for a user signup event:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     email: "john@example.com",
   *     name: "John Doe"
   *   }
   * }
   *
   * See https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send
   */
  webhook.payload = {
    personalizations: [
      {
        to: [{ email: webhook.payload.user.email }]
      }
    ],
    from: {
      email: "notifications@yourdomain.com",
      name: "Your App"
    },
    subject: "Welcome to Your App!",
    content: [
      {
        type: "text/html",
        value: `<h1>Welcome ${webhook.payload.user.name}!</h1>
                <p>Thank you for signing up to our service.</p>`
      }
    ]
  };

  return webhook;
}
```

### <ConnectorLogo name="resend" /> Resend [#resend]

The Resend connector lets your users send events as emails using Resend. Users enter their Resend API key in the [App Portal](/app-portal).

The transformation code should format the webhook payload according to [Resend's Email API](https://resend.com/docs/api-reference/emails/send-email).

Here's an example transformation for a user signup event:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     email: "john@example.com",
   *     name: "John Doe"
   *   }
   * }
   *
   * See https://resend.com/docs/api-reference/emails/send-email
   */
  webhook.payload = {
    from: "Your App <notifications@yourdomain.com>",
    to: [webhook.payload.user.email],
    subject: "Welcome to Your App!",
    html: `<h1>Welcome ${webhook.payload.user.name}!</h1>
           <p>Thank you for signing up to our service.</p>`
  };

  return webhook;
}
```

### <ConnectorLogo name="loops" /> Loops [#loops]

The Loops connector lets your users send events to Loops to trigger email automations. Users enter their Loops API key in the [App Portal](/app-portal).

The transformation code should format the webhook payload according to [Loops' Send Event API](https://loops.so/docs/api-reference/send-event).

Here's an example transformation for a user signup event:

```js
function handler(webhook) {
  /**
   * Example payload is:
   * {
   *   user: {
   *     email: "john@example.com",
   *     id: "user123"
   *   }
   * }
   *
   * See https://loops.so/docs/api-reference/send-event
   */
  webhook.payload = {
    email: webhook.payload.user.email,
    userId: webhook.payload.user.id,
    eventName: "user_signup",
    eventProperties: {
      source: "webhook"
    }
  };

  return webhook;
}
```

### <ConnectorLogo name="windmill" /> Windmill [#windmill]

The Windmill connector lets your users get a [Windmill](https://windmill.dev) webhook URL in a few clicks from the App Portal. It supports [Windmill Cloud](https://app.windmill.dev) as well as self-hosted Windmill instances.

![Connect to Windmill](/img/connectors/connect-to-windmill.png)

Since Windmill webhooks support arbitrary payloads, it does not require any custom transformation code.

### <ConnectorLogo name="inngest" /> Inngest [#inngest]

The Inngest connector lets your users send events to Inngest to trigger serverless functions. Users enter their Inngest API key in the [App Portal](/app-portal).

Since Inngest webhooks support arbitrary payloads, it does not require any custom transformation code.

### <ConnectorLogo name="zapier" /> Zapier [#zapier]

The Zapier connector lets your users send events to Zapier to trigger automations. It shows instructions on how to get a Zapier webhook URL.

Since Zapier Webhooks support arbitrary payloads, it does not require any custom transformation code.


### Custom Integration

In case you don't find a built-in integration for the service you want to connect to, you can create a custom integration. You can provide your own integration name and icon, and write instructions for your users on how to use it.

[Learn more about Custom Connectors](/connectors/custom-connector)

![Custom Integration](/img/connectors/custom-integration.png)

If you have a request for a built-in integration not listed above, [contact us](https://www.svix.com/contact/).


<!-- Source: https://docs.svix.com/consuming-webhooks -->

---
title: Consuming Webhooks
---
# Consuming Webhooks


In addition to helping you send webhooks to your users, we also help your users to easily verify the authenticity and security of the webhooks they receive from you.

<Callout type="info">

For information on how to verify webhooks, please head to the [Consuming Webhooks documentation](/receiving/introduction.mdx).

</Callout>
## Documentation for your users

We offer easy to use docs for how to safely consume webhooks which you can share with your users directly: [Consuming Webhooks documentation](/receiving/introduction.mdx).

## Building your own libraries

Depending on your product, you may want to offer additional processing before passing the verified payload for your customers. For example, you may want to create API objects from the payload that your users can use to interact with your API.

In this scenario you would want to create your own `Webhook` class equivalent that uses the `Svix` class internally. This way you can get all of the verification that Svix offer, while still being able to post-process the payload before passing it to your users.


<!-- Source: https://docs.svix.com/documenting-webhooks -->

---
title: Documenting Your Webhooks
---
# Documenting Your Webhooks


Once you're ready to launch your webhook feature, you'll need to add documentation.
At Svix we put a lot of effort into making it as easy as possible for our customers to send webhooks reliably at scale.
By extension, this includes helping our customers write great docs.

We recommend having 7 sections in your webhook docs: an intro, an explanation of available events and event types, instructions on how to add an endpoint, how to test endpoints, why and how to verify signatures, an explanation of the retry mechanism, and troubleshooting/failure recovery tips.

Here are some sample text and examples of each section to help you get started:

**The Intro**

The introduction to your webhook docs should give a brief explanation of what webhooks are and how to set them up.

Here's an example you can just copy and put in your docs:

```plaintext filename="The Intro"
Webhooks are how services notify each other of events.

At their core they are just a POST request to a pre-determined endpoint.
The endpoint can be whatever you want, and you can just add them from the UI.
You normally use one endpoint per service, and that endpoint listens to all of the event types.

For example, if you receive webhooks from Acme Inc., you can structure your URL like: https://www.example.com/acme/webhooks/.

The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s).

It's also important to disable CSRF protection for this endpoint if the framework you use enables them by default.

Another important aspect of handling webhooks is to verify the signature and timestamp when processing them.

You can learn more about it in the signature verification section.
```

Here is an example from one of our customers, Brex: [https://developer.brex.com/guides/webhooks](https://developer.brex.com/guides/webhooks)

**Events and Event Types**

The core value of webhooks is to notify users when events happen, so its extremely important to document what events are available and provide schemas and payload examples.

We make this very simple with our [Event Catalog](https://docs.svix.com/event-types#publishing-your-event-catalog) feature.

You can take a look at [Brex's docs](https://developer.brex.com/guides/webhooks) again for an example of the event catalog.
You can also preview your own event catalog in your Svix dashboard once you're added Event Types.

**How to Add an Endpoint**

After understanding what events they want to listen for, your users will need to specify an endpoint where they can receive the webhooks.

Sample text:

```plaintext filename="Adding an Endpoint"
In order to start listening to messages, you will need to configure your endpoints.

Adding an endpoint is as simple as providing a URL that you control and selecting the event types that you want to listen to.

If you don't specify any event types, by default, your endpoint will receive all events, regardless of type.

This can be helpful for getting started and for testing, but we recommend changing this to a subset later on to avoid receiving extraneous messages.

If your endpoint isn't quite ready to start receiving events, you can press the "with Svix Play" button to have a unique URL generated for you.

You'll be able to view and inspect webhooks sent to your Svix Play URL, making it effortless to get started.
```

**How to Test Endpoints**

Once a user specifies an endpoint, they'll want to test it to make sure its working correctly.

The simplest way to do this is to send test messages to the endpoint under the "Testing" tab.

Sample text:

```plaintext filename="Testing Endpoints"
Once you've added an endpoint, you'll want to make sure its working.

The "Testing" tab lets you send test events to your endpoint.

After sending an example event, you can click into the message to view the message payload, all of the message attempts, and whether it succeeded or failed.
```

**Signature Verification**

One of the most common ways that webhooks fail is a faulty signature verification mechanism.
The endpoint rejects a webhook thinking its fraudulent when in reality, they simply did the verification incorrectly.

We'll discuss common reasons for failed signature verification in the troubleshooting section.

Here our goal is to clearly explain how and why to verify signatures and provide code samples that users can simply copy/paste to get a working endpoint.

Sample text:

```plaintext filename="Verifying Signatures"
Webhook signatures let you verify that webhook messages are actually sent by us and not a malicious actor.

For a more detailed explanation, check out this article on [why you should verify webhooks](https://docs.svix.com/receiving/verifying-payloads/why).

Our webhook partner Svix offers a set of useful libraries that make verifying webhooks very simple. Here is a an example using Javascript:
```

Javascript sample:

```javascript filename="Javascript Code Sample"
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
const headers = {
  "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp": "1614265330",
  "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const rawBody = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
const verified = wh.verify(rawBody, headers);
```

For more instructions and examples of how to verify signatures, check out their [webhook verification documentation](https://docs.svix.com/receiving/verifying-payloads/how).

We also have some customers who simply link to our [webhook verification docs](https://docs.svix.com/receiving/verifying-payloads/how) directly (e.g. [Clerk](https://clerk.com/docs/integrations/webhooks/overview) and [incident.io](https://help.incident.io/en/articles/6984344-webhooks)) as they have code samples in 10 different languages.

**Retries**

Retries are one of the core features of Svix that make webhooks more reliable.
You want to let your users know under what conditions failed messages will be retried and when.

Sample text:

```plaintext filename="Retry Schedule"
Retries

We attempt to deliver each webhook message based on a retry schedule with exponential backoff.

The schedule

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

-   Immediately
-   5 seconds
-   5 minutes
-   30 minutes
-   2 hours
-   5 hours
-   10 hours
-   10 hours (in addition to the previous)

If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well.

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

Manual retries

You can also use the application portal to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date.
```

Lob does a great job of explaining and showing the retry schedule in their [webhook docs](https://help.lob.com/print-and-mail/getting-data-and-results/using-webhooks#retry-policy-7).

**Troubleshooting & Failure Recovery**

Adding tips on troubleshooting failing endpoints and how to recover from endpoint failures helps users get unstuck to minimize frustrations when setting up webhooks.

Sample text:

```plaintext filename="Troubleshooting Tips"
There are some common reasons why your webhook endpoint is failing:

Not using the raw payload body

This is the most common issue. When generating the signed content, we use the raw string body of the message payload.

If you convert JSON payloads into strings using methods like stringify, different implementations may produce different string representations of the JSON object, which can lead to discrepancies when verifying the signature. It's crucial to verify the payload exactly as it was sent, byte-for-byte or string-for-string, to ensure accurate verification.

Missing the secret key

From time to time we see people simple using the wrong secret key. Remember that keys are unique to endpoints.

Sending the wrong response codes

When we receive a response with a 2xx status code, we interpret that as a successful delivery even if you indicate a failure in the response payload. Make sure to use the right response status codes so we know when message are supposed to succeed vs fail.

Responses timing out

We will consider any message that fails to send a response within {timeout duration} a failed message. If your endpoint is also processing complicated workflows, it may timeout and result in failed messages.

We suggest having your endpoint simply receive the message and add it to a queue to be processed asynchronously so you can respond promptly and avoiding getting timed out.
```

Sample text for Failure Recovery:

```plaintext filename="Failure Recovery"
Re-enable a disabled endpoint

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. To re-enable a disabled endpoint, go to the webhook dashboard, find the endpoint from the list and select "Enable Endpoint".

Recovering/Resending failed messages

If your service has downtime or if your endpoint was misconfigured, you probably want to recover any messages that failed during the downtime.

If you want to replay a single event, you can find the message from the UI and click the options menu next to any of the attempts.

From there, click "resend" to have the same message send to your endpoint again.

If you need to recover from a service outage and want to replay all the events since a given time, you can do so from the Endpoint page. On an endpoint's details page, click  "Options > Recover Failed Messages".

From there, you can choose a time window to recover from.

For a more granular recovery - for example, if you know the exact timestamp that you want to recover from - you can click the options menu on any message from the endpoint page.

From there, you can click "Replay..." and choose to "Replay all failed messages since this time."
```

If you'd like us to take a look at your docs before or after your launch, just reach out and review them.


<!-- Source: https://docs.svix.com/email-notifications -->

---
title: Email Notifications
---
# Email Notifications

Svix supports sending personalized email notifications to your customers when certain events occur with their webhooks setup. This is useful for keeping customers aware of webhook delivery issues that might affect their integrations.


{/* ## How email notifications work */}

Email notifications are sent per [Consumer Application](/overview#consumer-applications). For example, when an endpoint for a particular Application is disabled due to repeated failures, Svix will send an email to the configured email address for that application.

## Setting up email notifications

### Enable email notifications in your organization

To get started, you'll need to enable email notifications for your organization. Head to the [Email Notifications](https://dashboard.svix.com/settings/organization/email-notifications) section of the Svix dashboard.

### Configure your branding

Personalize the email notifications by adding:
- Company name - The name of your company or service
- Logo URL - A link to your company logo for branding
- Webhooks management page URL - Where your customers can manage their webhook settings

### Set the email address for each application

For each application that should receive email notifications, you'll need to specify an email address. This is done by setting the `svix.email` field in the Application's `metadata`.

You can set the email address when creating an application, or by updating an existing application's metadata.

#### When creating an application

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
const app = await svix.application.create({
  name: "Example customer 123",
  uid: "example-customer-123",
  metadata: {
    "svix.email": "example-customer-123@example.com"
  }
});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, ApplicationIn

svix = Svix("AUTH_TOKEN")
app = svix.application.create(ApplicationIn(
    name="Example customer 123",
    uid="example-customer-123",
    metadata={
        "svix.email": "example-customer-123@example.com"
    }
))
```

</TabItem>
<TabItem value="Rust">

```rust
use svix::api::{ApplicationIn, Svix, SvixOptions};

let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let mut metadata = std::collections::HashMap::new();
metadata.insert("svix.email".to_string(), serde_json::Value::String("example-customer-123@example.com".to_string()));

let app = svix
    .application()
    .create(
        ApplicationIn {
            name: "Example customer 123".to_string(),
            uid: Some("example-customer-123".to_string()),
            metadata: Some(metadata),
            ..ApplicationIn::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
metadata := map[string]interface{}{
    "svix.email": "example-customer-123@example.com",
}
app, err := svixClient.Application.Create(ctx, &svix.ApplicationIn{
    Name: "Example customer 123",
    Uid:  "example-customer-123",
    Metadata: &metadata,
})
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.models.ApplicationIn;
import com.svix.models.ApplicationOut;
import com.svix.Svix;
import java.util.HashMap;
import java.util.Map;

Svix svix = new Svix("AUTH_TOKEN");
Map<String, Object> metadata = new HashMap<>();
metadata.put("svix.email", "example-customer-123@example.com");

ApplicationOut app = svix.getApplication().create(
    new ApplicationIn().name("Example customer 123").uid("example-customer-123").metadata(metadata)
);
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.models.ApplicationIn
import com.svix.kotlin.models.ApplicationOut
import com.svix.kotlin.Svix

val svix = Svix("AUTH_TOKEN")
val metadata = mapOf("svix.email" to "example-customer-123@example.com")

val applicationOut = svix.application.create(
    ApplicationIn(
        name = "Example customer 123",
        uid = "example-customer-123",
        metadata = metadata
    )
)
```

</TabItem>
<TabItem value="Ruby">

```ruby
require "svix"

svix = Svix::Client.new("AUTH_TOKEN")

application_out = svix.application.create(Svix::ApplicationIn.new({
    "name" => "Example customer 123",
    "uid" => "example-customer-123",
    "metadata" => {
        "svix.email" => "example-customer-123@example.com"
    }
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
var metadata = new Dictionary<string, object>
{
    { "svix.email", "example-customer-123@example.com" }
};

var applicationOut = await svix.Application.CreateAsync(
    new ApplicationIn(name: "Example customer 123", uid: "example-customer-123", metadata: metadata)
);
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$metadata = [
    'svix.email' => 'example-customer-123@example.com'
];

$applicationOut = $svix->application->create(
  ApplicationIn::create(
    name: 'Example customer 123'
  )
  ->withUid('example-customer-123')
  ->withMetadata($metadata)
);
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'
svix application create '{
  "name": "Example customer 123",
  "uid": "example-customer-123",
  "metadata": {
    "svix.email": "example-customer-123@example.com"
  }
}'
```

</TabItem>
<TabItem value="cURL">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'

curl -X POST "https://api.us.svix.com/api/v1/app/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer ${SVIX_AUTH_TOKEN}" \
    -d '{
      "name": "Example customer 123",
      "uid": "example-customer-123",
      "metadata": {
        "svix.email": "example-customer-123@example.com"
      }
    }'
```

</TabItem>
</CodeTabs>

#### Updating an existing application

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
await svix.application.patch("example-customer-123", {
  metadata: {
    "svix.email": "example-customer-123@example.com"
  }
});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix

svix = Svix("AUTH_TOKEN")
svix.application.patch("example-customer-123", {
    "metadata": {
        "svix.email": "example-customer-123@example.com"
    }
})
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let mut metadata = std::collections::HashMap::new();
metadata.insert("svix.email".to_string(), serde_json::Value::String("example-customer-123@example.com".to_string()));

let app = svix
    .application()
    .patch(
        "example-customer-123".to_string(),
        ApplicationPatch {
            metadata: Some(metadata),
            ..ApplicationPatch::default()
        },
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
metadata := map[string]interface{}{
    "svix.email": "example-customer-123@example.com",
}
app, err := svixClient.Application.Patch(ctx, "example-customer-123", &svix.ApplicationPatch{
    Metadata: &metadata,
})
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.Svix;
import com.svix.models.ApplicationPatch;
import java.util.HashMap;
import java.util.Map;

Svix svix = new Svix("AUTH_TOKEN");
Map<String, Object> metadata = new HashMap<>();
metadata.put("svix.email", "example-customer-123@example.com");

svix.getApplication()
  .patch("example-customer-123", new ApplicationPatch()
    .metadata(metadata)
  );
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Svix
import com.svix.kotlin.models.ApplicationPatch

val svix = Svix("AUTH_TOKEN")
val metadata = mapOf("svix.email" to "example-customer-123@example.com")

svix.application.patch("example-customer-123", ApplicationPatch(
    metadata = metadata
))
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
svix.application.patch("example-customer-123", Svix::ApplicationPatch.new({
    "metadata" => {
        "svix.email" => "example-customer-123@example.com"
    }
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
var metadata = new Dictionary<string, object>
{
    { "svix.email", "example-customer-123@example.com" }
};

await svix.Application.PatchAsync("example-customer-123", new ApplicationPatch(
    metadata: metadata
));
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$metadata = [
    'svix.email' => 'example-customer-123@example.com'
];

$svix->application->patch(
  'example-customer-123',
  ApplicationPatch::create()
  ->withMetadata($metadata)
);
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'
svix application patch 'example-customer-123' '{ "metadata": { "svix.email": "example-customer-123@example.com" } }'
```

</TabItem>
<TabItem value="cURL">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'

curl -X PATCH "https://api.us.svix.com/api/v1/app/example-customer-123/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer ${SVIX_AUTH_TOKEN}" \
    -d '{ "metadata": { "svix.email": "example-customer-123@example.com" } }'
```

</TabItem>
</CodeTabs>

### Redirecting to your webhooks management page

When the webhooks management page URL is included in emails, Svix adds `svix_app_id` as a query parameter, with the application ID as the value (or the UID if the application has one).

This can be used to redirect the user to the right page in your application, in cases where the URL varies per customer.

For example, if the webhooks management page URL in your site is `app.example.com/webhooks/customer-123`, set the webhooks management URL to `app.example.com/webhooks`. Then, in your application, add a redirect from `/webhooks/?svix_app_id={APP_UID}` to `/webhooks/{APP_UID}`.

### An example email notification

![Email notification example](/img/email-notification-example.png)


<!-- Source: https://docs.svix.com/endpoint-authentication -->

---
title: Advanced Endpoint Authentication
---
# Advanced Endpoint Authentication

Svix supports advanced endpoint authentication methods that can be used by your customers on top of the standard signature verification.

<Callout type="info">

These are advanced methods that are not required to keep your webhooks secure, but your customers might need them for their use case.
Read the [security docs](/security) for more information.

</Callout>
## Enabling OAuth and mTLS

OAuth and mTLS can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings).

![Enable Endpoint Authentication](/img/endpoint-authentication/endpoint-authentication-enable.png)

When enabled, your users will see an option in the [App Portal](/app-portal) to configure the respective authentication method on their endpoints.

![Endpoint Authentication Configure](/img/endpoint-authentication/endpoint-authentication-configure.png)

## OAuth
To configure OAuth, your users will need to enter a `Client ID` and the `Authorization Server URL`, as well as the rest of the OAuth parameters, depending on the desired `Grant type` and `Authentication method`.

![OAuth Authentication](/img/endpoint-authentication/endpoint-configure-oauth.png)

## Mutual TLS (mTLS)

With mTLS, your users can upload a private PEM encoded private key and certificate, which will be used to sign the requests sent to the endpoint, and to verify the identity of the receiving server.

![Mutual TLS Authentication](/img/endpoint-authentication/endpoint-configure-mtls.png)

For self-signed certificates, a custom Certificate Authority certificate can also be specified.


<!-- Source: https://docs.svix.com/event-types -->

---
title: Event Types
---
# Event Types

Each message sent through Svix has an associated event type.
Event types are identifiers denoting the type of message being sent.
Because they are the primary way for webhook consumers to configure what events they are interested in receiving, we highly recommend including an event catalog that describes each event type and provides sample payloads in your documentation.
To make it easy for webhook consumers to find and subscribe to the right events, Svix automatically generates an event catalog. See more about [publishing your event catalog here](#publishing-your-event-catalog).

Event types are just a string, for example: `user.signup`, `invoice.paid` and `workflow.completed`.

Webhook consumers can choose which events are sent to which endpoint. By default, all messages are sent to all endpoints. Though when adding or editing endpoints, users can choose to only subscribe to some of the event types for this particular endpoint.

<Callout type="default">

**Bulk Create**

It's recommended to add the event types you are going to use ahead of time. You can do it by [importing them from an OpenAPI spec](#import-event-types-from-an-openapi-specification) or [bulk creating them from code](#bulk-creating-event-types-from-code).

</Callout>
## What your users will see

This is how choosing event types look like in the [pre-built application portal](app-portal.mdx):

![Management UI screenshot](/img/event-type-selection.png)

## Event Type Format

Event types have a pattern defined a `^[a-zA-Z0-9\\-_.]+$`, meaning it can contain any of the following characters:

- A through Z (uppercase or lowercase)
- 0 through 9
- Special characters: `-`, `_`, `.`

<Callout type="default">

**Style guide**

We recommend you use period-delimited event type names (e.g. `<group>.<event>`). If you do, the App Portal UI will logically group them for your users and make it easier for them to subscribe an endpoint to all events in a particular group of event types.

</Callout>
## Using event types

You can add, edit, and delete event types in [the dashboard](https://dashboard.svix.com) or through the API below.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
const eventType = await svix.eventType.create({
  name: "user.signup",
  description: "A user has signed up",
});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, EventTypeIn

svix = Svix("AUTH_TOKEN")
app = svix.event_type.create(EventTypeIn(
    name="user.signup",
    description="A user has signed up"
))
```

</TabItem>
<TabItem value="Rust">

```rust
 let svix = Svix::new("AUTH_TOKEN".to_string(), None);
 let event_type = svix
     .event_type()
     .create(
         EventTypeIn {
             name: "user.signup".to_string(),
             description: "A user has signed up".to_string(),
             ..EventTypeIn::default()
         },
         None,
     )
     .await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
app, err := svixClient.EventType.Create(ctx, &svix.EventTypeIn{
    Name: "user.signup",
    Description: "A user has signed up",
})}
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.Svix;
import com.svix.models.EventTypeIn;


Svix svix = new Svix("AUTH_TOKEN");
svix.getEventType()
  .create(new EventTypeIn()
    .name("user.signup")
    .description("A user has signed up")
  );
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Svix;
import com.svix.kotlin.models.EventTypeIn;

val svix = Svix("AUTH_TOKEN");
svix.eventType.create(
                EventTypeIn(
                    name = "user.signup",
                    description = "A user has signed up",
                ));
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
svix.event_type.create(Svix::EventTypeIn.new({
        "name" => "user.signup",
        "description" => "A user has signed up"}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN");
await svix.EventType.CreateAsync(new EventTypeIn(
    name: "user.signup",
    description: "A user has signed up"
))
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$eventType = $svix->eventType->create(EventTypeIn::create(
    name: 'user.signup',
    description: 'A user has signed up'
));
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'
svix event-type create '{ "name": "user.signup", "description": "A user has signed up" }'
```

</TabItem>
<TabItem value="cURL">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'

curl -X POST "https://api.us.svix.com/api/v1/event-type/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer ${SVIX_AUTH_TOKEN}" \
    -d '{ "name": "user.signup", "description": "A user has signed up" }'
```

</TabItem>
</CodeTabs>

## Event Type Schema

One of the best ways to help your users integrate with you is by defining schemas for your event types. Event type schemas allow your users to anticipate the shape of the message body they will receive as well as introduce guardrails for each data type.

Schemas can be created using our visual schema editor, or by providing your own JSONSchema (Draft 7) spec either in the UI or [the API](https://api.svix.com/docs#tag/Event-Type/operation/v1.event-type.create).

![schema-editor-basic](/img/schema-editor-basic.png)

Once you have a schema defined, your users will be able to view the schema definition as well as an example event from the Event Catalog in the App Portal.

![schema-preview](/img/schema-preview.png)

To learn more about creating schemas, check out our guide on [adding your first event type schema](./tutorials/event-type-schema).

### Schema validation

Svix doesn't enforce the event type schema when creating a message. There are a few reasons to why we do it, though the main one is that we would much rather send a message with a bad schema, than block messages because the schema was slightly wrong. This is especially true for more strict schemas like ones that enforce some fields follow a specific regex (a potentially minor violation).

Additionally, since the payload is fully controlled by our customers (you), it's very easy to verify the schema on the sender side, before sending to Svix, which ensures people get exactly the level of validation they expect.

We do however love schemas and think they are super important, so we plan on adding an automatic SDK generator that will have type checked and validated schemas for you client side, so that bad schemas will fail at compile time, not run time!


## Import event types from an OpenAPI specification

The [OpenAPI specification](https://www.openapis.org/) is a formal standard for describing HTTP APIs. Some people write these by hand, and some automatically generate these from the web framework of their choice.

If you already have an OpenAPI specification, you can upload it to Svix which will automatically create event types for you based on the [`webhooks`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields) section (or `x-webhooks` for OpenAPI 3.0).

In addition to the standard features supported by the OpenAPI spec, Svix also supports a couple of extensions: `x-svix-feature-flags` and `x-svix-group-name` which let you set the [feature flags](#event-type-feature-flags) and group name on the event type respectively as follows:

```json
"webhooks": {
  "pet.new": {
    "post": {
      "operationId": "pet.new",
      "description": "A new pet has been created",
      "x-svix-feature-flags": ["beta-feature-a"],
      "x-svix-group-name": "group-name-1",
      "requestBody": {
        ...
      }
    }
  }
}
```

If your API spec has a `webhooks` section (or `x-webhooks`) you can continue to the next sections to learn how to upload it. If you need help with adding the `webhooks` section to your OpenAPI spec, please refer to the [Generating an OpenAPI spec section](#generating-an-openapi-spec).


### From the dashboard

Your first option for uploading your OpenAPI spec is by uploading it from the Svix dashboard. Once uploaded you'll be faced with this preview which will give you the opportunity to review the added event types before saving them.


![event-type-openapi](/img/event-type-openapi.png)

The event description, schema and examples will be used to create the Svix event type, using the `path id` as the event type name.
If you use choose the name of an already existing event type, it will be updated with the new values.

### Using the API

The API includes an endpoint which helps keep your [event-types in sync with a JSON OpenAPI Spec](https://api.svix.com/docs#tag/Event-Type/operation/v1.event-type.import-openapi).
Event types and their schemas are generated from `webhooks` or `x-webhooks` top-level key of the spec, just like with the UI importer.

When the event type already exists, it'll be updated with the latest description and schema, otherwise a new event type will be created.


<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js

const spec = loadOpenapiFromFile("openapi.json");
await svix.eventType.importOpenApi({ spec });

```

</TabItem>
<TabItem value="Python">

```python

spec = load_openapi_from_file("openapi.json")
svix.event_type.import_openapi(EventTypeImportOpenApiIn(spec=spec))

```

</TabItem>
<TabItem value="Rust">

```rust

let spec = load_openapi_from_file("openapi.json")?;
let _ = svix
    .event_type()
    .import_openapi(EventTypeImportOpenApiIn { spec }, None)
    .await?;

```

</TabItem>
<TabItem value="Go">

```go

spec := loadOpenapiFromFile("openapi.json")
svixClient.EventType.ImportOpenApi(context.Background(), svix.EventTypeImportOpenApiIn{
    Spec: spec,
})

```

</TabItem>
<TabItem value="Java">

```java

Map<String, Object> spec = MySpecReader.loadOpenapiFromFile("openapi.json");
svix.getEventType().importOpenApi(new EventTypeImportOpenApiIn().spec(spec));

```

</TabItem>
<TabItem value="Kotlin">

```kotlin

var spec = load_openapi_from_file("openapi.json")
var eventTypeImportOpenApiOut = await svix.EventType.ImportOpenapiAsync(
    new EventTypeImportOpenApiIn{spec: spec}
)

```

</TabItem>
<TabItem value="Ruby">

```ruby

spec = load_openapi_from_file("openapi.json")
event_type_import_open_api_out = svix.event_type.import_openapi(Svix::EventTypeImportOpenApiIn.new(spec))

```

</TabItem>
<TabItem value="C#">

```csharp

var spec = loadOpenapiFromFile("openapi.json")
var eventTypeImportOpenApiOut = await svix.EventType.ImportOpenapiAsync(
    new EventTypeImportOpenApiIn{
        spec: spec
    }
)

```

</TabItem>
<TabItem value="PHP">

```php
$spec = loadOpenapiFromFile('openapi.json');
$svix = new Svix('AUTH_TOKEN');

$eventTypeImportOpenApiOut = $svix->eventType->importOpenapi(
    EventTypeImportOpenApiIn::create()
      -> withSpec($spec)
);
```

</TabItem>
<TabItem value="CLI">

```shell
# TBD
```

</TabItem>
<TabItem value="cURL">

```shell

export SVIX_AUTH_TOKEN='AUTH_TOKEN'

curl -X POST "https://api.us.svix.com/api/v1/event-type/import/openapi/" \
-H  "Accept: application/json" \
-H  "Content-Type: application/json" \
-H  "Authorization: Bearer ${SVIX_AUTH_TOKEN}" \
-d '{"spec":' $(cat path/to/openapi.json) '}'

```

</TabItem>
</CodeTabs>

### Using the Github Action

Svix also provides a [Github Action](https://github.com/svix/svix-event-type-import-action) to upload your OpenAPI spec and automatically create or update your event types as part of your CI/CD pipeline.

```yaml
- name: Upload Event Types to Svix
  uses: svix/svix-event-type-import-action@v1.0.0
  with:
    openapi-file: 'path/to/your/openapi-spec.yml' # can be a .json too
    svix-api-key: ${{ secrets.SVIX_API_KEY }}
```


## Bulk creating event types from code

The easiest way to bulk-create event types is by just writing a simple script to load a [pipe delimited `CSV`](https://en.wikipedia.org/wiki/Comma-separated_values) file or a `JSON` file with the event types and make the API requests.

Here is an example `CSV` file (without headers) of events:

```csv
user.created|A user has been created
user.removed|A user has been removed
user.changed|A user has changed
```

Here are some example scripts for processing the above file:

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";
import fs from "fs";
import readline from "readline";

const svix = new Svix("AUTH_TOKEN");

async function execute() {
  const fileStream = fs.createReadStream("./data.csv");

  const data = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity,
  });

  for await (const lineItr of data) {
    const line = lineItr.split("|");
    const eventType = await svix.eventType.create({
      name: line[0],
      description: line[1],
    });
  }
}

execute();
```

</TabItem>
<TabItem value="Python">

```python
import json
from svix.api import Svix, EventTypeIn

svix = Svix("AUTH_TOKEN")

with open("./data.csv", "r") as f:
    for line in f:
        name, description = line.split("|")
        app = svix.event_type.create(EventTypeIn(
            name=name,
            description=description,
        ))
```

</TabItem>
<TabItem value="Rust">

```rust
use std::{error::Error, fs::File};
use svix::api::{EventTypeIn, Svix};

async fn execute() -> Result<(), Box<dyn Error>> {
    let svix = Svix::new("AUTH_TOKEN".to_string(), None);

    let mut reader = csv::ReaderBuilder::new()
        .delimiter(b'|')
        .from_reader(File::open("src/data.csv")?);

    for result in reader.records() {
        let record = result?;

        svix.event_type()
            .create(
                EventTypeIn {
                    name: record[0].to_string(),
                    description: record[1].to_string(),
                    ..EventTypeIn::default()
                },
                None,
            )
            .await?;
    }

    Ok(())
}

#[tokio::main]
async fn main() {
    execute().await.unwrap();
}
```

</TabItem>
<TabItem value="Go">

```go
package main

import (
	"bufio"
	"log"
	"os"
	"strings"

	svix "github.com/svix/svix-webhooks/go"
)

func main() {
	svixClient := svix.New("AUTH_TOKEN", nil)

	f, err := os.Open("./data.csv")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	scanner := bufio.NewScanner(f)
	for scanner.Scan() {
		line := strings.Split(scanner.Text(), "|")
		_, err = svixClient.EventType.Create(ctx, &svix.EventTypeIn{
			Name:        line[0],
			Description: line[1],
		})
		if err != nil {
			log.Println(err)
		}
	}
	if err := scanner.Err(); err != nil {
		log.Fatal(err)
	}
}
```

</TabItem>
<TabItem value="Java">

```java
package sviximport;

import java.io.FileReader;
import java.io.IOException;
import java.util.Scanner;
import com.svix.Svix;
import com.svix.models.EventTypeIn;
import com.svix.exceptions.ApiException;

public class App {

    public static void main(String[] args) {
        Svix svix = new Svix("AUTH_TOKEN");

        try (Scanner scanner = new Scanner(new FileReader("/path/to/data.csv"));) {
            while (scanner.hasNextLine()) {
                try {
                    String[] line = scanner.nextLine().split("|");
                    svix.getEventType().create(new EventTypeIn().name(line[0]).description(line[1]));
                } catch(ApiException e) {
                    if (e.getCode() != 409) {
                        System.out.println(e.getResponseBody());
                        System.exit(1);
                    }
                }
            }
        } catch(IOException e) {
            System.out.println(e.toString());
            System.exit(1);
        }
    }
}
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
package sviximport

import com.svix.kotlin.Svix
import com.svix.kotlin.models.EventTypeIn
import com.svix.kotlin.exceptions.ApiException
import java.io.File
import java.io.IOException
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess

fun main() = runBlocking {
    val svix = Svix("AUTH_TOKEN")
    try {
        File("/path/to/data.csv").useLines { lines ->
            lines.forEach {
                try {
                    val line = it.split("|")
                    svix.eventType.create(EventTypeIn(
                        name = line[0],
                        description = line[1]
                    ))
                } catch (e: ApiException) {
                    println(e.message)
                    exitProcess(1)
                }
            }
        }
    } catch (e: IOException) {
        println(e.toString())
        exitProcess(1)
    }
}
```

</TabItem>
<TabItem value="Ruby">

```ruby
require "svix"
require "csv"

svix = Svix::Client.new("AUTH_TOKEN")

CSV.foreach('data.csv', {:col_sep => "|"}) do |line|
    event_type = svix.event_type.create(Svix::EventTypeIn.new({
        "name" => line[0],
        "description" => line[1]}))
end
```

</TabItem>
<TabItem value="C#">

```csharp
// Example TBD
// Read the CSV and create event types
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$handle = fopen('./data.csv', 'r');
if ($handle) {
    while (($line = fgets($handle)) !== false) {
        $parts = explode('|', trim($line));
        $name = $parts[0];
        $description = $parts[1];

        $eventType = $svix->eventType->create(EventTypeIn::create(
            name: $name,
            description: $description
        ));
    }
    fclose($handle);
}
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'

while IFS=$'|', read -r name description
do
    svix event-type create "{ \"name\": \"${name}\", \"description\": \"${description}\" }"
done < data.csv
```

</TabItem>
<TabItem value="cURL">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'

while IFS=$'|', read -r name description
do
    curl -X POST "https://api.us.svix.com/api/v1/event-type/" \
        -H  "Accept: application/json" \
        -H  "Content-Type: application/json" \
        -H  "Authorization: Bearer ${SVIX_AUTH_TOKEN}" \
        -d  "{ \"name\": \"${name}\", \"description\": \"${description}\" }"
done < data.csv
```

</TabItem>
</CodeTabs>

## Publishing your Event Catalog

By default, your event types are only accessible to users from within an authenticated session on the Application Portal.

If you would like to have them publicly accessible, you can enable the "Make Public" setting from the Event Catalog configuration screen in the Dashboard settings.

Enabling this setting will cause your event types to be statically served on **svix.com**. You can link or embed that site within your own documentation.

![event-catalog-config](/img/event-catalog-config.png)

### Configuration Options

- **Make Public:** Whether or not the Event Catalog will be publicly accessible from **svix.com**.
- **Display Name:** _Required to make your Event Catalog public._ The display name will be shown in the heading of the published page. It should be the name of your company or product.

### Using a custom domain

It is also possible to have the Event Catalog served from your own domain (e.g. `webhooks.example.com`) instead of the default `www.svix.com`.

To set this up, please set the following record on your DNS provider:
* Type: `CNAME`
* Name: `webhooks` (or whatever subdomain you would like to use)
* Value: `event-types.svix.com`

And [let us know](https://www.svix.com/contact/) once you do so that we can activate it on our end.

### What it looks like

![event-catalog-published](/img/event-catalog-published.png)

## Event type feature flags

When introducing new features in your application it can be useful to only expose them to a select set of users.

Event types can be hidden from users by setting feature flags on them. If a feature flag is set on an event type, users won't see the event type in the Event Catalog and the API, unless they have an authorization token that explicitly allows them.

A feature flag is an arbitrary string that you can set at event type creation time. You can also remove or add back the feature flag by updating an existing event type. Feature flags follow the same naming rules as the event type name itself: `^[a-zA-Z0-9\\-_.]+$`.

Here's how you can create an event type with a feature flag:

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
const eventType = await svix.eventType.create({
  name: "user.signup",
  description: "A user has signed up",
  featureFlags: ["beta-feature-a"],
});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, EventTypeIn

svix = Svix("AUTH_TOKEN")
app = svix.event_type.create(EventTypeIn(
    name="user.signup",
    description="A user has signed up",
    feature_flags=["beta-feature-a"]
))
```

</TabItem>
<TabItem value="Rust">

```rust
use svix::api::{ApplicationIn, Svix, SvixOptions};

let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let event_type = svix
    .event_type()
    .create(
        EventTypeIn {
            name: "user.signup".to_string(),
            description: "A user has signed up".to_string(),
            feature_flags: Some(vec!["beta-feature-a".to_string()]),
            ..EventTypeIn::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
app, err := svixClient.EventType.Create(ctx, &svix.EventTypeIn{
    Name: "user.signup",
    Description: "A user has signed up",
    FeatureFlag: []string{"beta-feature-a"},
})}
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.Svix;
import com.svix.models.EventTypeIn;


Svix svix = new Svix("AUTH_TOKEN");
svix.getEventType()
    .create(new EventTypeIn()
    .name("user.signup")
    .description("A user has signed up")
    .featureFlags(new String[]{"beta-feature-a"})
  );
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Svix;
import com.svix.kotlin.models.EventTypeIn;

val eventTypeOut = svix.eventType.create(EventTypeIn()
    .name("user.signup")
    .description("A user has signed up")
    .featureFlags(arrayOf("beta-feature-a"))
)
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
svix.event_type.create(Svix::EventTypeIn.new({
    "name": "user.signup",
    "description": "A user has signed up",
    "feature_flags": ["beta-feature-a"]
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN");
await svix.EventType.CreateAsync(new EventTypeIn{
    name: "user.signup",
    description: "A user has signed up",
    featureFlags: new string[] {"beta-feature-a"}
});
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$eventType = $svix->eventType->create(
  EventTypeIn::create(
    name: 'user.signup',
    description: 'A user has signed up'
  )
    ->withFeatureFlags(['beta-feature-a'])
);

```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'
svix event-type create '{ "name": "user.signup", "description": "A user has signed up", "featureFlags": ["beta-feature-a"] }'
```

</TabItem>
<TabItem value="cURL">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'

curl -X POST "https://api.us.svix.com/api/v1/event-type/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer ${SVIX_AUTH_TOKEN}" \
    -d '{ "name": "user.signup", "description": "A user has signed up", "featureFlags": ["beta-feature-a"] }'
```

</TabItem>
</CodeTabs>

If a user tries to retrieve this newly created event type they will get a not-found error. To give them access you need to give them an access token that explicitly allows them to see event types with at least one of the feature flags set during creation.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
const svix = new Svix("AUTH_TOKEN");
const dashboard = await svix.authentication.appPortalAccess("app_Xzx8bQeOB1D1XEYmAJaRGoj0", {
    featureFlags: ["beta-feature-a"]
});
// A URL that automatically logs user into the dashboard
console.log(dashboard.url);
```

</TabItem>
<TabItem value="Python">

```python
svix = Svix("AUTH_TOKEN")
dashboard = svix.authentication.app_portal_access("app_Xzx8bQeOB1D1XEYmAJaRGoj0", AppPortalAccessIn(
    feature_flags=["beta-feature-a"]
))
# A URL that automatically logs user into the dashboard
print(dashboard.url)
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let dashboard = svix
    .authentication()
    .app_portal_access(
        "app_Xzx8bQeOB1D1XEYmAJaRGoj0".to_string(),
        AppPortalAccessIn {
            feature_flags: Some(vec!["beta-feature-a".to_string()]),
            ..Default::default()
        },
        None,
    )
    .await?;
// A URL that automatically logs user into the dashboard
println!("{}", dashboard.url);
```

</TabItem>
<TabItem value="Go">

```go
svixClient := svix.New("AUTH_TOKEN", nil)
dashboard, _ := svixClient.Authentication.AppPortalAccess(ctx, "app_Xzx8bQeOB1D1XEYmAJaRGoj0", &svix.AppPortalAccessIn{
    FeatureFlags: []string{"beta-feature-a"}
})
// A URL that automatically logs user into the dashboard
fmt.Println(dashboard.Url)
```

</TabItem>
<TabItem value="Java">

```java
Svix svix = new Svix("AUTH_TOKEN");
AppPortalAccessOut dashboard = svix.getAuthentication().appPortalAccess("app_Xzx8bQeOB1D1XEYmAJaRGoj0", new AppPortalAccessIn()
    .featureFlags(new String[]{"beta-feature-a"})
);
// A URL that automatically logs user into the dashboard
System.out.println(dashboard.getUrl());
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val svix = Svix("AUTH_TOKEN")
val dashboard = svix.authentication.appPortalAccess("app_Xzx8bQeOB1D1XEYmAJaRGoj0", AppPortalAccessIn()
    .featureFlags(arrayOf("beta-feature-a"))
)
// A URL that automatically logs user into the dashboard
println(dashboard.url)
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
dashboard = svix.authentication.app_portal_access("app_Xzx8bQeOB1D1XEYmAJaRGoj0", Svix::AppPortalAccessIn.new({
    "feature_flags": ["beta-feature-a"]
}))
# A URL that automatically logs user into the dashboard
puts dashboard.url
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN");
var dashboard = await svix.Authentication.AppPortalAccessAsync("app_Xzx8bQeOB1D1XEYmAJaRGoj0", new AppPortalAccessIn{
    featureFlags: new string[] {"beta-feature-a"}
});
// A URL that automatically logs user into the dashboard
Console.WriteLine(dashboard.Url)
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');


$dashboard = $svix->authentication->appPortalAccess(
    'app_Xzx8bQeOB1D1XEYmAJaRGoj0',
    AppPortalAccessIn::create()
      -> withFeatureFlags(['beta-feature-a'])
);

echo $dashboard->url . PHP_EOL;
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN="AUTH_TOKEN"
svix authentication app-portal app_Xzx8bQeOB1D1XEYmAJaRGoj0 '{
    "featureFlags": ["beta-feature-a"]
}'
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X POST "https://api.us.svix.com/api/v1/auth/app-portal-access/app_Xzx8bQeOB1D1XEYmAJaRGoj0/" \
    -H  "Accept: application/json" \
    -H  "Authorization:  Bearer AUTH_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"featureFlags": ["beta-feature-a"]}'
```

</TabItem>
</CodeTabs>

A user with this newly minted dashboard access token will be able to see this new event type.

Once you're ready to release this new event type to all of your users simply remove the feature flag from it.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
const svix = new Svix("AUTH_TOKEN");
await svix.eventType.update("user.signup", { featureFlag: null });
```

</TabItem>
<TabItem value="Python">

```python
svix = Svix("AUTH_TOKEN")
svix.event_type.update("user.signup", EventTypeUpdate(feature_flag=None))
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let event_type_out = svix
    .event_type()
    .update(
        "user.signup".to_string(),
        EventTypeUpdate {
            feature_flag: None,
            ..Default::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
svixClient := svix.New("AUTH_TOKEN", nil)
eventTypeOut, _ := svixClient.EventType.Update(ctx, "user.signup", &svix.EventTypeUpdate{ FeatureFlag: nil })
```

</TabItem>
<TabItem value="Java">

```java
Svix svix = new Svix("AUTH_TOKEN");
EventTypeOut eventTypeOut = svix.getEventType().update("user.signup", new EventTypeUpdate()
    .featureFlag(null)
);
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val svix = Svix("AUTH_TOKEN")
val eventTypeOut = svix.eventType.update("user.signup", EventTypeUpdate().featureFlag(null))
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
event_type_out = svix.event_type.update("user.signup", Svix::EventTypeUpdate.new({
    "feature_flag": nil
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN");
var eventTypeOut = await svix.EventType.Update("user.signup", new EventTypeUpdate{
    featureFlag: null
});
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');


$eventTypeOut = $svix->eventType->update(
  'user.signup',
  EventTypeUpdate::create(description: 'updated description')
    ->withFeatureFlag(null)
);
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN="AUTH_TOKEN"
svix event-type update user.signup '{"featureFlag": null}'
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X POST "https://api.us.svix.com/api/v1/event-type/user.signup/" \
    -H  "Accept: application/json" \
    -H  "Authorization:  Bearer AUTH_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"featureFlag": null}'
```

</TabItem>
</CodeTabs>

<Callout type="info">

**Important**

Keep in mind that endpoints with no event type filtering will receive all messages regardless of feature flags.

Feature flags only impact event types' visibility in the app portal, catalog, and the API; not their deliverability. This means that endpoints with no event type filtering will receive all messages regardless of feature flags.

Additionally, if a user is subscribed to a feature flagged event, they will continue to be able to see it in the app portal regardless of whether the feature flag is enabled for them or not.

</Callout>
## Appendix

### Generating an OpenAPI spec

While most web frameworks support generating OpenAPI specs, not all of them support generating the new `webhooks` section (added in OpenAPI 3.1).

If your framework of choice already support webhooks you are probably good to go, just make sure that it generates it correctly. Here's an example of how a `pet.new` event type should look like in your OpenAPI file:

```json
"webhooks": {
  "pet.new": {
    "post": {
      "operationId": "pet.new",
      "description": "A new pet has been added",
      "x-svix-feature-flags": ["beta-feature-a"],  // Optional field
      "x-svix-group-name": "group-name-1",  // Optional field
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "tag": {
                  "type": "integer"
                }
              }
            },
            "example": {
              "name": "Buddy",
              "tag": 1234
            }
          }
        }
      }
    }
  }
}
```

If your framework doesn't support generating a `webhooks` section, or if your webhooks section is not generated correctly, you can resort to generating the section yourself using a simple post-processing script that adds the `webhooks` section to your spec.

One alternative is to write the section manually and then have code to inject it into the OpenAPI spec. A better alternative is to use your web framework's auto-generation to do some of the heavy lifting for you.

You can make your web framework generate the types for you by creating a dummy model that includes all of your submodels. Here is a Python example:

```python
class PetNewEvent(pydantic.BaseModel):
    """A new pet has been added"""

    event_type = "pet.new"
    foo: str
    bar: str

...

class WebhookTypes(BaseModel):
    """All of the webhook types that we support"""

    a1: PetNewEvent
    a2: PetChangedEvent
    a3: PetDeletedEvent
```

This will generate the schemas for all of your event types. Once you have those, you can write a script to generate the `webhooks` for you, or you can generate it manually. The result should look something like this:


```json
"webhooks": {
  "pet.new": {
    "post": {
      "operationId": "pet.new",
      "description": "A new pet has been added",
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PetNewEvent"
            },
            "example": {
              "event_type": "pet.new",
              "foo": "Example 1",
              "bar": "Example 2",
            }
          }
        }
      }
    }
  }
  // ...
}
```


<!-- Source: https://docs.svix.com/faq -->

---
title: Frequently Asked Questions (FAQ)
---
# Frequently Asked Questions (FAQ)


Here are some frequently asked questions about Svix.

### How long does it take to integrate with Svix?

Most teams wire up our SDK and start sending webhooks in under a day. Many small companies ship in a few hours; while larger enterprise roll-outs that include design reviews and QA typically budget ~two weeks from first commit to production.

### I already have an event stream, how do I connect to Svix?

Having an existing event stream makes integrating Svix even easier. All you need to do is either create a consumer that reads from the event stream and uses the Svix [`message.create`](https://api.svix.com/docs#tag/Message/operation/v1.message.create) API directly or connect [Svix Bridge](/sending-messages-with-bridge) to read event directly from the stream.

### Build vs. buy a webhooks service?

We created Svix because we believe that when it comes to webhooks, buying is much
preferable to building. Buying means that you don't have to spend your precious
engineering time and effort onto maintaining the webhooks system. For a thorough
comparison, please refer to the <a className="underline" href="https://www.svix.com/build-vs-buy/">build vs. buy</a> matrix.

### How do you ensure that customers only receive events pertaining to them and aren't affected by other customers?

In Svix, each one of your customers will have its own [Consumer Application](/overview#consumer-applications) which is where you will be sending messages to. Each Consumer Application will only get messages sent to it, and Consumer Applications are completely isolated from other Consumer Applications on the database level.

### How do my customers subscribe to receive webhooks?

Svix offers an [embeddable Consumer Application Portal](https://www.svix.com/application-portal/) that you can fully white-label to match your UI (or build your own with the API).
From there your customers will be able to add endpoints, pick event types, view logs, and replay deliveries without ever needing a Svix account.

### We have time-sensitive and business critical events, how does your platform ensure reliability and message delivery guarantees?

Svix queues every message durably, delivers with low latency, and retries on an exponential back-off schedule until it succeeds or exhausts the policy, giving you at-least-once delivery even under network hiccups or spikes.

### What is your outage recovery process?

If your service or a customer endpoint is down, you (or the customer) can replay all failed messages for a chosen time window straight from the Portal, or resend individual webhooks, ensuring nothing is lost once both systems are back online.

### What support options are available and what are your SLAs?

All tiers include email & community support. The Enterprise tier also offers 24/7 access to on-call engineers and custom support SLAs.
For full information about the support and uptime SLAs options, please refer to the [Svix Pricing page](https://www.svix.com/pricing/).

### Can Svix handle our scale?

We process billions of webhooks a year for our customers, and we power webhooks for top companies like Brex and Lob. We can most likely handle your scale, but please reach out if you have any specific questions or requirements.

### Will my customers know that we are using Svix?

No. Your customers don't need to know you are using Svix.

Though we always appreciate our customers spreading the word about Svix. :)

### What happens when a customer endpoint is down?

Failed attempts trigger the automatic retry schedule; all tries (and responses) are logged for transparency. After the final attempt the message is marked failed but retained, so the customer (or you) can later replay it once the endpoint is healthy.

### What are webhooks?

Webhooks are user-defined HTTP callbacks for server-to-server communication. You can think of them as a reverse-API or asynchronous API notifications. An API call is how a server can make requests from another service, and webhooks are how that service would asynchronously notify the server of events.


### What is webhooks as a service?

Webhooks as a service refers to Svix's software as a service (SaaS) webhook platform. We've built a user interface for managing your users' webhook subscriptions as well as an API that simplifies the process of implementing webhook best practices at scale.

### Are Svix webhooks secure?

Yes! Our webhook service was designed for security from the ground up. We follow industry best practices, encrypt all data both in transit and at rest, and are compliant with SOC 2 Type II, GDPR, CCPA and more.


### How to test and debug webhooks?

There most common way for testing and debugging webhooks is by pushing test events from the service you are testing to either a receiver that can show you the events, or to a proxy tool that can forward requests to your development machine. Svix Play supports both!


### How can I test webhooks locally?

Svix Play integrates seamlessly with the Svix CLI, allowing you to relay webhooks to your local development environment. This means you can test webhook integrations locally without exposing your development server to the internet.

### Can I test webhooks for free?

Yes! You can use Svix Play to test your webhooks completely for free. You don't even need to signup to use any of it, including the web UI, and the forwarding CLI.


<!-- Source: https://docs.svix.com/get-help -->

---
title: Get Help & Chat With Us
---
# Get Help & Chat With Us


We love chatting with developers!

If anything is unclear, you have some feedback, or you would just like to chat please get in touch! You can join the community on Slack or reach out via email at contact@svix.com. We are also happy to jump on a call, so just drop us a line.

<SlackJoinLink />


<!-- Source: https://docs.svix.com/idempotency -->

---
title: Idempotency
---
# Idempotency

Svix supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

<Callout type="info">

This section is about making API calls to Svix. For information on helping your customers ensure they only get a message once, please refer to [receiving idempotency section (deduplication)](#receiving-idempotency-deduplication) below.

</Callout>
To perform an idempotent request, pass the idempotency key in the `Idempotency-Key` header to the request. The idempotency key should be a unique value generated by the client. You can create the key in however way you like, though we suggest using UUID v4, or any other string with enough entropy to avoid collisions.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
const svix = new Svix("AUTH_TOKEN");
const message = {
  eventType: "invoice.paid",
  eventId: "evt_Wqb1k73rXprtTm7Qdlr38G",
  payload: {
    type: "invoice.paid",
    id: "invoice_WF7WtCLFFtd8ubcTgboSFNql",
    status: "paid",
    attempt: 2,
  },
};
await svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", message, {
    idempotencyKey: "fd56a56b-838d-4456-8b83-390802672895",
});
```

</TabItem>
<TabItem value="Python">

```python
svix = Svix("AUTH_TOKEN")
message = MessageIn(
    event_type="invoice.paid",
    event_id="evt_Wqb1k73rXprtTm7Qdlr38G",
    payload={
        "type": "invoice.paid",
        "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        "status": "paid",
        "attempt": 2
    }
)
svix.message.create(
    "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    message,
    PostOptions(idempotency_key="fd56a56b-838d-4456-8b83-390802672895")
)
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_owned(), None);
svix.message()
    .create(
        "app_Xzx8bQeOB1D1XEYmAJaRGoj0".to_owned(),
        MessageIn {
            event_type: "invoice.paid".to_owned(),
            event_id: Some("evt_Wqb1k73rXprtTm7Qdlr38G".to_owned()),
            payload: json!({
                "type": "invoice.paid",
                "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
                "status": "paid",
                "attempt": 2
            }),
            ..MessageIn::default()
        },
        Some(PostOptions {
            idempotency_key: Some("fd56a56b-838d-4456-8b83-390802672895".to_owned()),
        }),
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
svixClient := svix.New("AUTH_TOKEN", nil)
eventId := "evt_Wqb1k73rXprtTm7Qdlr38G"
message := svix.MessageIn{
    EventType: "invoice.paid",
    EventId: *svix.NullableString(&eventId),
    Payload: map[string]interface{}{
        "type":    "invoice.paid",
        "id":      "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        "status":  "paid",
        "attempt": 2,
    },
}
idempotencyKey := "fd56a56b-838d-4456-8b83-390802672895"
svixClient.Message.CreateWithOptions(ctx, "app_Xzx8bQeOB1D1XEYmAJaRGoj0", &message, &svix.PostOptions{
    IdempotencyKey: &idempotencyKey,
})
```

</TabItem>
<TabItem value="Java">

```java
Svix svix = new Svix("AUTH_TOKEN");

MessageIn message = new MessageIn()
    .eventType("invoice.paid")
    .eventId("evt_Wqb1k73rXprtTm7Qdlr38G")
    .payload("{" +
        "\"type\": \"invoice.paid\"," +
        "\"id\": \"invoice_WF7WtCLFFtd8ubcTgboSFNql\"," +
        "\"status\": \"paid\"," +
        "\"attempt\": 2" +
    "}");

PostOptions opts = new PostOptions()
    .idempotencyKey("fd56a56b-838d-4456-8b83-390802672895");

svix.getMessage()
    .create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", message, opts);
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val svix = Svix("AUTH_TOKEN")
svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    MessageIn(
        eventType = "invoice.paid",
        payload = mapOf<String, Any>(
            "type" to "invoice.paid",
            "id" to "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status" to "paid",
            "attempt" to 2
        ),
        eventId = "evt_Wqb1k73rXprtTm7Qdlr38G"),
    PostOptions(
        idempotencyKey = "fd56a56b-838d-4456-8b83-390802672895"))
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
svix.message.create(
    "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    Svix::MessageIn.new({
        "event_type" => "invoice.paid",
        "payload" => {
            "type": "invoice.paid",
            "id" => "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status" => "paid",
            "attempt" => 2
        },
        "event_id" => "evt_Wqb1k73rXprtTm7Qdlr38G"}),
    { "idempotency_key" => "fd56a56b-838d-4456-8b83-390802672895" })
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
var message = new MessageIn(
    eventType: "invoice.paid",
    payload: new {
        type = "invoice.paid",
        id = "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        status = "paid",
        attempt = 2
    },
    eventId: "evt_Wqb1k73rXprtTm7Qdlr38G"
);
await svix.Message.CreateAsync(
    "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    message,
    null,
    "fd56a56b-838d-4456-8b83-390802672895"
);
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$message = MessageIn::create(
  eventType: 'invoice.paid',
  payload: [
    'type' => 'invoice.paid',
    'id' => 'invoice_WF7WtCLFFtd8ubcTgboSFNql',
    'status' => 'paid',
    'attempt' => 2
  ]
)->withEventId('evt_Wqb1k73rXprtTm7Qdlr38G');

$svix->message->create(
  'app_Xzx8bQeOB1D1XEYmAJaRGoj0',
  $message,
  new MessageCreateOptions(idempotencyKey: 'fd56a56b-838d-4456-8b83-390802672895')
);
```

</TabItem>
<TabItem value="CLI">

```
Idempotency is not yet supported in the Svix CLI.
```

</TabItem>
<TabItem value="cURL">

```shell
curl "https://api.us.svix.com/api/v1/app/app_Xzx8bQeOB1D1XEYmAJaRGoj0/msg/" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer AUTH_TOKEN" \
    -H "Idempotency-Key: fd56a56b-838d-4456-8b83-390802672895"
    -d '{ "eventType": "invoice.paid", "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G", "payload": { "type": "event.type", "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status": "paid", "attempt": 2 } }'
```

</TabItem>
</CodeTabs>

Svix's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key for any successful request. Subsequent requests using the same auth token and the same idempotency key will return the same result for a period of up to 12 hours.

Please note that idempotency is only supported for `POST` requests.


## Receiving idempotency (deduplication)

Svix offers "at least once" delivery semantics. This means that if there are issues during delivery (e.g. networking issues) a message can sometimes be processed twice by the webhook receiver.

In many cases this is not a concern, and recipients can just process the duplicated requests. Though when "exactly once" semantics are required, webhook consumers can use Svix's webhook deduplication support to ensure that.

Svix includes a `webhook-id` header with every webhook request. That ID is unique per message but is reused across retries of the same message. Consumers can then use this identifier to ensure that they only process each event once, by for example storing the ID in redis with a 24hr expiry, and checking whether they already processed the message's `webhook-id` before processing it.


<!-- Source: https://docs.svix.com/incoming-webhooks -->

---
title: Operational Webhooks
---
# Operational Webhooks


In addition to enabling you to send webhooks to your customers, Svix also sends you webhooks about the events in your Svix environment. We call these: "Operational webhooks".

These webhooks let you build powerful workflows and automations over events in your account. For example, a common one is to monitor for [`endpoint.disabled`](https://api.svix.com/docs#tag/Webhook/operation/endpoint.disabled), which triggers when an endpoint has been automatically disabled after multiple days of failing, and notify your customer automatically via email when that happens.

To subscribe to operational webhooks, please head to the [Operational Webhooks](https://dashboard.svix.com/webhooks) section of the dashboard.

For more information on the exact events, their schemas, and other related documentation please refer to the [the webhooks section](https://api.svix.com/docs#tag/Webhook) of the API reference documentation.


<!-- Source: https://docs.svix.com/ingest/receiving-with-ingest -->

---
title: Receiving Webhooks with Ingest
---
# Receiving Webhooks with Ingest

Receiving webhooks with [Svix Ingest] starts by creating a `Source`.

A `Source` generates an endpoint you can share with a webhook provider as a
destination for their webhooks.

Ingest supports signature verification schemes and flows used by a variety of
webhook providers, including `adobeSign`, `airwallex`, `clerk`, `docusign`,
`github`, `hubspot`, `open-ai`, `resend`, `shopify`, `slack`, `stripe`, `zoom`,
and many others. Check out [the product][Svix Ingest] to see the full list.

Additionally there's the option to configure a `Source` as `genericWebhook` to
skip performing signature verification. This is useful for providers that have
no verification scheme and for providers whose verification scheme is not yet
supported by Ingest.

<Callout type="default">

Don't see your provider? Let us know and we'll add it!

</Callout>
## Create a Source

Creating a `Source` from the [Ingest Dashboard]:

![screenshot of the Ingest Dashboard showing the overview tab for a Source named "demo"](/img/ingest/source-edit.png)

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","CLI","cURL"]}>
<TabItem value="JavaScript">

```javascript
  const svix = new Svix("AUTH_TOKEN");
  const ingestSourceOut = await svix.ingest.source.create({
    name: "myGithubWebhook",
    uid: "unique-identifier",
    type: "github",
    config: {
        secret: "SECRET"
    },
  });
  ```

</TabItem>
<TabItem value="Python">

```python
  svix = Svix("AUTH_TOKEN")
  ingest_source_out = svix.ingest.source.create(IngestSourceIn(
    name="myGithubWebhook",
    uid="unique-identifier",
    type="github",
    config=GithubConfig(
        secret="SECRET"
    ),
  ))
  ```

</TabItem>
<TabItem value="Rust">

```rust
  let svix = Svix::new("AUTH_TOKEN".to_string(), None);
  let ingest_source_out = svix.ingest().source().create(
      IngestSourceIn {
          name: "myGithubWebhook".to_owned(),
          uid: Some("unique-identifier".to_owned()),
          config: IngestSourceInConfig::Github(GithubConfig {
              secret: "SECRET".to_owned(),
              ..Default::default()
          }),
          ..Default::default()
      },
      None,
  ).await?;
  ```

</TabItem>
<TabItem value="Go">

```go
  svixClient := svix.New("AUTH_TOKEN", nil)
  ingestSourceOut, err := svixClient.Ingest.Source.Create(
    ctx,
    &IngestSourceIn{
        Name: "myGithubWebhook",
        Uid: "unique-identifier",
        Type: IngestSourceInTypeGithub,
        Config: GithubConfig{
            Secret: "SECRET",
        },
    },
  )
  ```

</TabItem>
<TabItem value="Java">

```java
  Svix svix = new Svix("AUTH_TOKEN");
  IngestSourceOut ingestSourceOut = svix
    .getIngest()
    .getSource()
    .create(new IngestSourceIn()
        .name("myGithubWebhook")
        .uid("unique-identifier")
        .config(new IngestSourceInConfig.Github(new GithubConfig()
          .secret("SECRET")
        ))
    );
  ```

</TabItem>
<TabItem value="Kotlin">

```kotlin
  val svix = Svix("AUTH_TOKEN")
  val ingestSourceOut = svix.ingest.source.create(IngestSourceIn(
    name = "myGithubWebhook",
    uid = "unique-identifier",
    config = IngestSourceInConfig.Github(GithubConfig(
        secret = "SECRET"
    )),
  ))
  ```

</TabItem>
<TabItem value="Ruby">

```ruby
  svix = Svix::Client.new("AUTH_TOKEN")
  ingest_source_out = svix.ingest.source.create(Svix::IngestSourceIn.new({
    "name": "myGithubWebhook",
    "uid": "unique-identifier",
    "config": Svix::IngestSourceInConfig::Github.new({
      "secret": "SECRET"
    })
}))
  ```

</TabItem>
<TabItem value="C#">

```csharp
  var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
  var ingestSourceOut = await svix.Ingest.Source.CreateAsync(
    new IngestSourceIn{
        Name = "myGithubWebhook",
        Uid = "unique-identifier",
        Config = IngestSourceInConfig.Github(new GithubConfig {
            Secret = "SECRET",
        }),
    }
  );
  ```

</TabItem>
<TabItem value="CLI">

```shell
  svix ingest source create '{
    "name": "myGithubWebhook",
    "uid": "unique-identifier",
    "type": "github",
    "config": {
        "secret": "SECRET"
    }
  }'
  ```

</TabItem>
<TabItem value="cURL">

```shell
  curl -X 'POST' \
    'https://api.eu.svix.com/ingest/api/v1/source' \
    -H 'Authorization: Bearer AUTH_TOKEN' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "myGithubWebhook",
        "uid": "unique-identifier",
        "type": "github",
        "config": {
            "secret": "SECRET"
        }
    }'
  ```

</TabItem>
</CodeTabs>

## Tell your provider where to send webhooks

The Ingest URL is also listed on the [Ingest Dashboard] for each `Source`.

The `IngestSourceOut` response from the API will include an `ingestUrl` which is
the endpoint you give to your provider, telling them where to send their
webhooks. Given an ingest URL of the format
`https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567`,
providers can actually send requests to any trailing path, and with any query parameter; e.g.,
`https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567/foo/bar/baz?qux=duck`.

Trailing path segments will be forwarded along to the eventual destination under the `svix-ingest-trailing-path-segments` header;
query parameters will be forwarded under the `svix-ingest-query` header. Both
are and are also available as [transformations](./transformations.mdx)
parameters.

For GitHub, as is used in this example, this is referred to as the
_"Payload URL"_.


## Managing incoming messages

In the [Ingest Dashboard], the Destinations tab for your `Source` is where you
can configure endpoints, view logs, inspect message payloads, etc.

![screenshot of the Ingest Dashboard showing the Destination/Endpoints tab for a Source named "demo"](/img/ingest/destination-endpoints.png)

Configuring endpoints allows you to forward messages received by Ingest over to endpoints of your choosing.

![screenshot of the Ingest Dashboard showing the Destination/Logs tab for a Source named "demo"](/img/ingest/destination-logs.png)

Logs and statistics are available to help monitor for problems, replay or
recover messages.


## Managing Source Tokens

The last portion of the Ingest URL is a `Token` which can be
invalidated and rotated:

![screenshot of the Ingest Dashboard showing the overview tab for a Source named "demo"](/img/ingest/url-token-rotate.png)

`Token`s that are rotated stay usable for 24 hours. During this time both the
old and new `Token`s are honored by Ingest. During this period it's important
that you reconfigure your provider with the new Ingest URL in order to have a
seamless transition.

## Verifying Webhooks

Verifying webhooks forwarded by Svix Ingest works the same way as verifying webhooks sent by Svix
Dispatch. Check [How to Verify Webhooks with the Svix Libraries][verify-libs] and the following
pages for ways to ensure only legitimate requests get processed at your destination endpoint(s).

[Svix Ingest]: https://svix.com/ingest
[Ingest Dashboard]: https://dashboard.svix.com/ingest
[verify-libs]: https://docs.svix.com/receiving/verifying-payloads/how


<!-- Source: https://docs.svix.com/ingest/source-errors -->

---
title: Source Errors
---
# Source Errors


In the Source Errors tab, you can see the log of all the incoming webhooks that were rejected by the Source.
The most likely reason for a source error is an invalid signature, or an invalid payload format in the incoming message.

Every time your Ingest URL returns a non-200 status code, the reason for the failure will be logged here, and the incoming message will not be delivered to your endpoints.

![Source Errors tab](/img/ingest/source-errors.png)

In the error details, you can inspect the message payload, the HTTP method and headers, and the reason for the failure.

![Source Error details](/img/ingest/source-errors-details.png)


<!-- Source: https://docs.svix.com/ingest/transformations -->

---
title: Transformations
---
# Transformations


Ingest Transformations are a powerful Svix feature that allows the modification of certain webhook properties in-flight.
With transformations, you can write JavaScript code to change a webhook's HTTP method, target URL, and body payload before it's sent to your endpoint.

## Using Transformations

Ingest Transformations are available in all plans. To use them, after creating an endpoint in a Source, go to the 'Advanced' tab and scroll down to the 'Transformations' card:

![Ingest Transformations card](/img/ingest/ingest-transformation.png)

An endpoint's Transformation can be enabled or disabled at any time by toggling the switch on this card.

You can write Javascript code to edit an endpoint's Transformation, and test your code against a sample incoming payload to see the result.

![Editing an endpoint's Transformation](/img/ingest/edit-transformation.png)

### How to write a Transformation

Svix expects a Transformation to declare a function named `handler`. Svix will pass an object with the following properties to the function:

- `method`, a string representing the HTTP method the webhook will be sent with. It is always `"POST"` by default, and its only valid values are `"POST"`, `"PUT"`, or `"PATCH"`.
- `url`, a string representing the destination endpoint's URL. It can be changed to any valid URL.
- `payload`, which contains the webhook's payload as a JSON object. It can be changed as needed.
- `eventType`, a string representing the event type. Changes to it are ignored. This will always have the value `svix.in` for ingest events
- `transformationsParams`, additional parameters made available in ingest; see below for details

The Transformation must return the same object, but may modify its properties as described above.
In addition to the ones listed above, it can also set the following properties on the returned object:

- `cancel`, a boolean which controls whether or not to cancel the dispatch of a webhook. This value defaults to `false`.
- `headers`, an object with keys being HTTP header names and values being the associated header values. Headers set here take precedence over endpoint headers.

### An example Transformation

Suppose that sometimes, you want to redirect webhooks to a custom URL instead of the endpoint's defined URL. And you only want to do this redirect if a custom URL is present in the webhook payload. You can write a transformation like this:

```js
function handler(webhook) {
	if (webhook.payload.customUrl) {
		webhook.url = webhook.payload.customUrl;
	}
	return webhook;
}
```

Great, the webhook is redirected to the custom URL if the `customUrl` property exists on the payload. Otherwise, it is sent to the endpoint's defined URL.

### Ingest-Specific Transformations Params

Transformations called from an Ingest request will receive additional parameters under the `transformationsParams` property. Specifically:

- `transformationsParams.headers` will be a string/string key-value map containing the headers of the input request. If a header is duplicated on the input request, the values will be concatenated with ", ", as per [RFC 9110 § 5.2](https://www.rfc-editor.org/info/rfc9110/#section-5.2).
- `transformationsParams.headers.svix-ingest-query` contains the un-parsed query string (the part after the `?` on the request URL)
- `transformationsParams.headers.svix-ingest-trailing-path-segments` contains any parts of the URL after the token, not including the first `/`.

If your source URL is `https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567` and your provider makes a request to `https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567/foo/bar/baz?qux=duck`, `transformationsParams.headers["svix-ingest-query"]` will contain the string `qux=duck` and `transformationsParams.headers["svix-ingest-trailing-path-segments"]` will contain the string `foo/bar/baz`.


<!-- Source: https://docs.svix.com/integrations/advanced-zapier -->

---
title: Advanced Zapier Integrations
---
# Advanced Zapier Integrations

[Zapier](https://zapier.com/) is an online automation tool that connects apps and services.
You can build a Zapier integration that allows your customers to connect your service to other services with Svix.

The Svix auto-generated Zapier integration is a Node/JavaScript project meaning it's defined as code and very easy to customize.

This doc gives guidance on ways to enhance your Zapier webhook integration powered by Svix.

<Callout type="info">

**Prerequisites**

Before reading this doc, we strongly recommend reading the [Build a Zapier Integration](./zapier) docs.
This doc assumes you're familiar with the basics of Svix Integrations and have a functional API key-based Zapier webhook integration.

</Callout>
## Upgrade an existing integration

If you add or change your event types, you may want to upgrade your Zapier integration to a new auto-generated integration.

### Upgrading to an updated auto-generated package

Follow the [Download the package](./zapier#download-the-package) section of the [Build a Zapier Integration](./zapier) guide to download an updated auto-generated package. Then follow the steps below to link the new package to the existing integration and deploy.

#### Build and deploy

After downloading and extracting the auto-generated integration package, download the package dependencies:

```
npm install
```

Then, link the new integration package to your existing Zapier integration using the Zapier CLI [link command](https://platform.zapier.com/cli_docs/cli#link):
```
zapier link
```

Finally, build & deploy the integration to Zapier through the [push command](https://platform.zapier.com/cli_docs/cli#push):
```
zapier push
```

### Managing integration versions

If you wish to version bump your integration, be sure to update your integration's `package.json` (shown below) to reflect the new version number. It defaults to `1.0.0`.

```json
{
    "name": "zapier-webhook-integration-with-svix",
    "version": "1.0.0", // <------ CHANGE ME
    "main": "index.js",
    // << truncated >>
}
```

Zapier supports complex versioning use cases including migrating users during a version bump. Review the [Zapier Platform](https://platform.zapier.com/cli_docs/docs#deploying-an-app-version) docs for more information.

### Upgrading a customized integration

If you have customized your integration package, you will need to manually reconcile the diff.
We strongly recommend using version control like git to track the changes and aid in merging.

## Alternative authentication schemes

By default, the auto-generated Zapier integration uses [custom (API key)](https://platform.zapier.com/cli_docs/docs#custom) authentication type and requires users to explicitly provide an application ID and integration key.
The default scheme might be undesirable because it requires the user to copy-paste credentials and doesn't connect to your existing auth flows.

To provide a better user experience that hides the Svix constructs, we recommend using [OAuth2](https://platform.zapier.com/cli_docs/docs#oauth2) or [Session](https://platform.zapier.com/cli_docs/docs#session) authentication. See the [Zapier Platform authentication](https://platform.zapier.com/cli_docs/docs#authentication) docs for more information.
- With OAuth2, Zapier will redirect your user to your site where you can authenticate them and send Zapier back an access token. An demonstration of this flow's user experience is shown in the video below.
- With Session Auth, Zapier will show a login form for your user to provide their username and password. Those are securely sent to your service where you'll send Zapier back a session token.

With either authentication flow, you can make another request to your APIs to exchange the access/session token for the Svix application ID and integration key.
An example of that API endpoint for a Flask-based service might look like the following:

```py
svix = Svix("AUTH_TOKEN")

@app.route('/webhook/integration/')
@auth_required
def get_svix_integration_key():
    app_id = ... # get your user's app id
    integration_out = svix.integration.create(app_id, IntegrationIn(
        name="Zapier Integration"
    ))
    ... # store your user's zapier integration ID
    key_out = svix.integration.get_key(app_id, integration_out.id)
    return jsonify({
        "application_id": app_id,
        "integration_key": key_out.key
    })
```

### OAuth2 Flow User Experience

<div style={{position: "relative", paddingBottom: "69.23076923076923%", height: 0}}>
    <iframe src="https://www.loom.com/embed/128a2f1c2da94a84a6c1b23bf9d16343" frameborder={"0"} webkitallowfullscreen mozallowfullscreen allowfullscreen style={{
    position: "absolute", top: 0, left: 0, width: "100%", height: "100%"}}></iframe>
</div>

## Custom triggers

### Multiple event types per trigger

If you wish to configure triggers with multiple event types, you can modify the `filterTypes` field on the create endpoint operation during the trigger's subscribe hook.

If you wish your users to specify a set of event types when creating the trigger, you can use Zapier's [input fields](https://platform.zapier.com/cli_docs/docs#input-fields) feature.

### Additional trigger fields

By default, the auto-generated integration contains the example payload that you provided with the event type schema. Zapier supports explicitly defining the list of output fields for the trigger. If you have optional fields or multiple event types with different schemas, we recommend explicitly defining the [output fields](https://platform.zapier.com/cli_docs/docs#output-fields) on the trigger.

### Adding custom actions or triggers

The auto-generated Zapier integration can be extended with additional actions, triggers, creates, or other Zapier resources. More information on this is available on the [Zapier CLI platform docs](https://platform.zapier.com/cli_docs/docs).

The Zapier CLI can modify your package (e.g. creating a new action from a template). More information on that is available on the [Zapier CLI Reference](https://platform.zapier.com/cli_docs/cli).


<!-- Source: https://docs.svix.com/integrations/ngrok -->

---
title: Using the ngrok Integration
---
# Using the ngrok Integration


[ngrok](https://ngrok.com) is a staple tool for many developers that creates tunnels between networks. It is often used to expose a port on localhost to the public Internet, but with ngrok Cloud Edge it can be also be used to secure traffic from the Internet to production cloud environments.

In this tutorial, we will learn how to verify Svix webhook requests using ngrok both for local development and on ngrok Cloud Edge.

<Callout type="info">

This tutorial assumes you are already familiar with the [Svix webhooks service](https://www.svix.com) and [ngrok](https://ngrok.com). If this is your first time using Svix,
we recommend you first check out our [quickstart documentation](https://docs.svix.com/overview). We also recommend checking out ngrok's documentation on [Webhook Verification](https://ngrok.com/docs/http/webhook-verification/).

</Callout>
## Verify Svix webhooks locally with ngrok CLI

### Install ngrok
If you haven't already, [install the ngrok CLI](https://ngrok.com/download).

### Create a tunnel

First, create an endpoint in the Consumer App Portal, and copy the endpoint's Signing Signature. Then, run the following ngrok command on your computer's terminal, replacing SIGNATURE with the Signing Signature you just copied:

```sh
ngrok http 3000 --verify-webhook=svix --verify-webhook-secret=SIGNATURE
```

When you run the command, ngrok should generate URL that looks like `https://d7f4c8296c55.ngrok.io`. Copy that URL, and set it as the URL for the Svix endpoint you previously created in the Consumer App Portal.

Assuming you are running a service on port 3000, all Svix webhooks to your endpoint will now be forwarded to that local service by ngrok. And because you configured the `--verify-webhook` and `--verify-webhook-secret` options, ngrok will only forward verified Svix webhooks.

## Verify Svix Webhooks on ngrok Cloud Edge

### Create a Svix endpoint

Create an endpoint in the consumer application portal. You'll need the newly-created endpoint's Signing Signature later on.

### Sign up for ngrok

Create an account on [ngrok.com](https://ngrok.com).

### Create an ngrok Edge

Login to the [ngrok dashboard](https://dashboard.ngrok.com). Using the menu on the left, expand "Cloud Edge" and choose "Edges." Create an edge by clicking the "New edge" button and choose "HTTPS Edge".

### Configure ngrok Edge

On the Edge configuration page, find and click the "Webhooks Verification" menu item, and click "Begin Setup." Choose Svix as your webhook provider:

![Selecting Svix as the Webhook Provider](/img/ngrok-webhook-provider.png)

And paste your endpoint's Signing Signature from Svix as the webhook signing key:

![Entering your Svix endpoint's Signing Key](/img/ngrok-signing-key.png)


<!-- Source: https://docs.svix.com/integrations/zapier -->

---
title: Building a Zapier Integration
---
# Building a Zapier Integration

[Zapier](https://zapier.com/) is an online automation tool that connects apps and services.
Svix can automatically build a Zapier integration for you directly from your Svix account. This lets your customers easily build Zapier workflows on top of your service.

It generates a trigger for each event type and a special trigger that subscribes to all event types. The integration package also comes with secure webhook verification enabled by default.

This guide will walk you through the steps to set up a Zapier integration for your users. You can see the end user experience (using the default API key auth) in the video below.

<div style={{position: "relative", paddingBottom: "69.23076923076923%", height: 0}}>
    <iframe src="https://www.loom.com/embed/74241c13e8454af29676723ddc1d334d" frameborder={"0"} webkitallowfullscreen mozallowfullscreen allowfullscreen allow="fullscreen" sandbox="allow-scripts allow-forms allow-same-origin allow-presentation" style={{
    position: "absolute", top: 0, left: 0, width: "100%", height: "100%"}}></iframe>
</div>

## Prerequisites

### Set up event type schemas

Before setting up a Zapier integration, we strongly recommend configuring event types with schemas and examples as those will be embedded in the auto-generated integration package.

Follow the [Your first event type schema](/tutorials/event-type-schema) tutorial and refer to the [Event Types](/tutorials/event-type-schema) docs to set this up.

### Set up Zapier CLI

<Callout type="info">

**Information**

Zapier integrations can be defined on the Zapier UI or via the Zapier CLI (as a Node/JavaScript package). This guide is based on the CLI which allows for more powerful customizations. We recommend reading through the [How to Use REST Hooks in Zapier CLI](https://platform.zapier.com/cli_tutorials/resthooks) tutorial provided by Zapier to get an understanding of the structure.

</Callout>
The Zapier integration package requires [Node.js v14](https://nodejs.org/) as that is the version used by the Zapier platform at runtime. Install the Zapier CLI globally:

```
npm install -g zapier-platform-cli
```

Make a [Zapier Platform](https://developer.zapier.com/) account and login:
```
# Login with username and password
zapier login

# Login with SSO
zapier login --sso
```

## Create an integration

### Download the package

You can download an auto-generated integration package from the [integrations page](https://dashboard.svix.com/integrations) on the dashboard shown below.

![zapier-integration-generator](/img/zapier-integration-generator.png)

### Generate integration keys

To integrate Svix with Zapier REST Hooks, the Zapier integration needs access to your user's application to add a Zapier endpoint.
Svix provides an Integrations API to generate long-lived rotatable credentials called integration keys for this purpose.

On your service, return the Svix application ID and integration secret to your user. See the [Integration section](http://api.svix.com/docs#tag/Integration) of the API docs for more information.

Code example including application creation:

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
const app = await svix.application.create({ name: "Test Application" });
const integ = await svix.integration.create(app.id, { name: "Zapier Integration" });
const integKey = await svix.integration.getKey(app.id, integ.id);
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, ApplicationIn, IntegrationIn

svix = Svix("AUTH_TOKEN")
app_id = svix.application.create(ApplicationIn(name="Test Application")).id
integ_id = svix.integration.create(app_id, IntegrationIn(name="Zapier Integration")).id
integ_key = svix.integration.get_key(app_id, integ_id).key
```

</TabItem>
<TabItem value="Rust">

```rust
// TBD
```

</TabItem>
<TabItem value="Go">

```go
import (
    svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
appOut, err := svixClient.Application.Create(ctx, &svix.ApplicationIn{
    Name: "Test Application",
})}
integOut, err := svixClient.Integration.Create(ctx, appOut.Id, &svix.IntegrationIn{
    Name: "Zapier Integration",
})
integKeyOut, err := svixClient.Integration.GetKey(ctx, appOut.Id, integOut.Id)
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.Svix;
import com.svix.models.ApplicationIn;
import com.svix.models.IntegrationIn;

Svix svix = new Svix("AUTH_TOKEN");
String appId = svix.getApplication().create(new ApplicationIn().name("Test Application")).id;
String integId = svix.getIntegration().create(appId, new IntegrationIn().name("Zapier Integration")).id;
String integKey = svix.getIntegration().getKey(appId, integId).key;
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Svix;
import com.svix.kotlin.models.ApplicationIn;
import com.svix.kotlin.models.IntegrationIn;

val svix = Svix("AUTH_TOKEN");
val appId = svix.application.create(ApplicationIn().name("Test Application")).id
val integId = svix.integration.create(appId, IntegrationIn().name("Zapier Integration")).id
val integKey = svix.integration.getKey(appId, integId).key
```

</TabItem>
<TabItem value="C#">

```csharp
// TBD
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$app = $svix->application->create(ApplicationIn::create(
  name: 'Test Application'
));

$integ = $svix->integration->create($app->id, IntegrationIn::create(
  name: 'Zapier Integration'
));

$integKey = $svix->integration->getKey($app->id, $integ->id);
```

</TabItem>
<TabItem value="CLI">

```shell
svix application create '{"name": "Test Application"}'
svix integration create 'app_24D5XFE8W4VVYQ2XPdJlFKlYKrf' '{"name": "Zapier Integration"}'
svix integration get-key 'app_24D5XFE8W4VVYQ2XPdJlFKlYKrf' 'integ_24D5mQaRudh54XvMNMmgUroNfRA'
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X 'POST' \
  'https://api.us.svix.com/api/v1/app/' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Test Application",
}'

curl -X 'POST' \
  'https://api.us.svix.com/api/v1/app/APP_ID/integration/' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Zapier Integration"
}'

curl -X 'GET' \
  'https://api.us.svix.com/api/v1/app/APP_ID/integration/INTEG_ID/key/' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

```

</TabItem>
</CodeTabs>


### Build and deploy

After downloading and extracting the auto-generated integration package, download the package dependencies:

```
npm install
```

Then, create a new Zapier integration using the Zapier CLI [register command](https://platform.zapier.com/cli_docs/cli#register):
```
zapier register
```

Finally, build & deploy the integration to Zapier through the [push command](https://platform.zapier.com/cli_docs/cli#push):
```
zapier push
```

### That's it!

You're done! You have a working Zapier integration for your Svix-powered webhooks. :)

Try it out! The next section walks through the experience of creating a Zap with a webhook trigger.
Then read on to see how you can customize your integration and release it publicly on the Zapier website.

![congratulations](/img/congratulations.png)

## Try it out

You can create a Zap with a Svix-powered webhook trigger from the account where you deployed the integration. You try it out from another account by obtaining the share link on the [Zapier Platform console](https://developer.zapier.com/).

### Set up the trigger

1. Start by going to the [Zap editor](https://zapier.com/app/editor/) and give your Zap a name.
2. Select the integration (aka "app"). You can search for it by name (the same name you set when calling `zapier register`).
3. Select a trigger event. This corresponds to an event type (or the all trigger for all event types) which the Zap will be triggered on.

![zap-creation-step-1](/img/zap-creation-step-1.png)

### Authenticate

#### Retrieve the integration key for your application

Your users should use the mechanism you provide to generate integration keys, but for testing you can use the Svix CLI to obtain an application ID and integration key.

```bash
$ svix application create '{"name": "Test Application"}'
{
  "name": "Test Application",
  "id": "app_24D5XFE8W4VVYQ2XPdJlFKlYKrf", # <------------------- Application ID
  "createdAt": "2022-01-25T23:12:34.055654Z",
  "updatedAt": "2022-01-25T23:12:34.055694Z"
}
$ svix integration create 'app_24D5XFE8W4VVYQ2XPdJlFKlYKrf' '{"name": "Zapier Integration"}'
{
    "name": "Zapier Integration",
    "id": "integ_24D5mQaRudh54XvMNMmgUroNfRA",
    "createdAt": "2022-01-25T23:14:34.876543+00:00",
    "updatedAt": "2022-01-25T23:14:35.019512+00:00"
}
$ svix integration get-key 'app_24D5XFE8W4VVYQ2XPdJlFKlYKrf' 'integ_24D5mQaRudh54XvMNMmgUroNfRA'
{
    "key": "testintegsk_zrHyRLxf7qMed4sv2onkoearKUgHWkK9"  # <--- Integration Key
}
```


#### Create Account

Zapier will prompt you to sign in to an account for the integration. When you create a new account,  enter the application ID and integration key from the previous step.

![zap-creation-step-2](/img/zap-creation-step-2.png)

<Callout type="info">

**User Authentication Experience**

By default, the auto-generated Zapier integration uses token-based auth where your users input the application ID and an integration key. You can set up OAuth or Session-based authentication schemes to mask these Svix constructs by following the guide in the [Advanced Zapier Integrations](./advanced-zapier#alternative-authentication-schemes) doc.

</Callout>
### Test the trigger

Finally, test your trigger by sending a test message. Zapier will prompt you to test your integration. Upon attempting it, Zapier will register a new endpoint on the application (which will also show in the App Portal).

![zap-creation-step-3](/img/zap-creation-step-3.png)

In the App Portal, send a test event for the corresponding event type to the trigger's endpoint.

![zap-creation-step-3.1](/img/zap-creation-step-3.1.png)

In Zapier, re-run the trigger test. Once successful, Zapier will automatically populate the fields available based on the example's message. If you skipped sending the test message, the fields provided in the event schema example will be shown.

![zap-creation-step-4](/img/zap-creation-step-4.png)

### Set up an action

You can now set up an action that uses any of these available fields.

![zap-creation-step-5](/img/zap-creation-step-5.png)

## Next Steps

### Release it live

You can see your integration on the [Zapier Platform](https://developer.zapier.com/). From there you can edit the icon and title, get the sharable link for your users, and view analytics.

If you wish to make the integration generally available on the Zapier website, you'll need to submit it for review to Zapier. More information on this process can be found on the Zapier [lifecycle planning docs](https://platform.zapier.com/partners/lifecycle-planning). Zapier also provides [integration review guidelines](https://platform.zapier.com/partners/integration-review-guidelines) that describe the requirements for release.

### Advanced Customizations

You can configure additional triggers, set up authentication schemes like OAuth2 or Session-based, and much more within the Zapier platform. We recommend reading our [Advanced Zapier Integrations](./advanced-zapier) docs page and going through the extensive [Zapier CLI Platform](https://platform.zapier.com/cli_docs/docs) docs.


<!-- Source: https://docs.svix.com/introduction -->

---
title: Introduction
slug: /
---
# Introduction


Svix makes sending webhooks easy and reliable by offering [webhook sending as a service](https://www.svix.com). With Svix you can start sending webhooks in minutes, while ensuring robust deliverability, and a great developer experience for your users.

## Webhooks are harder than they seem.

Webhooks require a lot more engineering time, resources, and ongoing maintenance than you would first expect.

When building your own webhooks you have to deal with a lot of challenges, such as: unreliable user endpoints, which fail or hang more often than you think; monitoring and reliability of your webhook system; security implications which are unique to webhooks and much more.

This is where we come in. With Svix you can start sending webhooks in under five minutes, and we take care of all of the above and more.

<AgentSkillsCallout />


<!-- Source: https://docs.svix.com/message-tags -->

---
title: Message Tags
---
# Message Tags

Message tags are free-form strings that can be added to messages to use them for filtering.

In some cases, while debugging webhooks, you may want to get a specific message with a certain field or attribute in the payload, beyond it's event type or channel.

## How to use it

To use message tags, simply add the `tags` field to the create message call. For example, if you want to give your users the option to filter messages related to a specific user id, you can add the user id as a tag.

```typescript
await svix.message.create('app_id', {
    eventType: "user.signup",
    tags: ["user_1"],
    payload: {
        "user_id": "user_1",
        "email": "test@example.com"
    },
});
```

Usually, tags contain values that are already present in the payload, such as user ids, order ids, product categories, etc.

Tags will be visible in the Application Portal, and your users will be able to use them to filter messages.

![Message Tags in the Application Portal](/img/message-tags.png)

They can also be used via the API when [listing messages](https://api.svix.com/docs#tag/Message/operation/v1.message.list) or [message attempts](https://api.svix.com/docs#tag/Message-Attempt/operation/v1.message-attempt.list-attempted-messages).

## When not to use it

Tags are not meant as a way to route messages to specific endpoints or specific customers, that's what [event types](./event-types) and [channels](./channels) are for.

Message tags have no impact on message delivery. They are only meant to be used for message filtering.


<!-- Source: https://docs.svix.com/onboarding -->

---
title: Onboarding
---
# Onboarding

The onboarding document has now been merged with the rest of the documentation. In order to get started just navigate to the [main docs section](./introduction.mdx).


<!-- Source: https://docs.svix.com/opentelemetry-streaming -->

---
title: OpenTelemetry Streaming
---
import OpenTelemetryProviderNotes from './_common/otel-provider-notes.mdx'

# OpenTelemetry Streaming

<Callout type="info">

**Important**

OpenTelemetry streaming is only available as part of the Enterprise tier. Please refer to [the pricing page](https://www.svix.com/pricing/) for more information.
Some of this functionality can also be achieved by using [Operational Webhooks](/incoming-webhooks).

</Callout>
Svix offers OpenTelemetry streaming as a way to stream webhook delivery traces to observability platforms that support OpenTelemetry such as Datadog, Grafana, Coralogix, and most other observability platforms.

## What does Svix send

Svix sends OpenTelemetry traces as two spans: the outer span `message_attempt` and the inner span `http_attempt`.

Both spans include the following attributes:
```rust
start: DateTime<Utc>  // Included as the span start time (not a field)
end: DateTime<Utc>    // Included as the span end time (not a field)
org_id: OrganizationId
app_id: ApplicationId
app_uid: Option<ApplicationUid>
endpoint_id: EndpointId
msg_id: MessageId
msg_event_id: Option<MessageUid>
event_type: EventTypeName,
attempt_count: u16
status: MessageStatus
```

And the inner `http_attempt` also has:
```rust
http.response.status_code: i16
```

Here is an example of how it looks like in an observability dashboard:

![OpenTelemetry Spans](/img/opentelemetry-spans.png)


### Additional attributes
You have the flexibility to add your own custom attributes to spans at either the app level or per event.

#### Application attributes
You can add additional otel attributes per app by adding key-value pairs to an application's
metadata, prefixing the key with `otel.`. Example:
```json
{
  "metadata": { "otel.custom-app-key-1": "custom-app-value-1" }
}
```

The param `custom-app-key-1=custom-app-value-1` will be added to your spans.

#### Event attributes
You can add additional per-event attributes to your spans by passing custom key-value pairs in `transformationsParams.otel`
when calling the Create Message endpoint. Example:
```json
{
  "payload": { "abc": "123" },
  "eventType": "my-event",
  "transformationsParams": {
    "otel": {
      "custom-key-1": "custom-value-1",
      "custom-key-2": "custom-value-2",
    }
  }
}
```

## Configuring OpenTelemetry in the Dashboard
Configure OpenTelemetry settings in the Observability section of Dashboard settings. Once you've input the URL and optional headers, you can test functionality directly in the browser.
![Configure OpenTelemetry](/img/opentelemetry-config.png)

## How to use it

The raw spans sent by Svix can be used in a variety of ways:
* Deriving graphs and metrics for your observability dashboards.
* Alerting for when specific customers fail over a certain threshold or their latency increases.
* Storing raw delivery logs for compliance reasons.
* Much more...

<OpenTelemetryProviderNotes />

### Video: Integrating with Grafana Cloud
This video shows how you can quickly integrate Svix OpenTelemetry exports with Grafana Cloud.
<div style={{marginTop: "1rem", width: "100%", maxWidth: "30rem", aspectRatio: "16/9"}}>
  <iframe
    width="100%"
    height="100%"
    src="https://www.youtube-nocookie.com/embed/hzZBloVfjEU"
    allowFullScreen
  />
</div>


<!-- Source: https://docs.svix.com/overview -->

---
title: Entities Overview
---
# Entities Overview

This section provides an overview of the common Svix entities.

The Svix entities are mostly hierarchical with the environment being the main isolation unit, below it there are applications which represent a target for messages, and even below there are endpoints which represent a destination to send webhooks to.

![Entities diagram](/img/entity-graph.svg)


## IDs and UIDs

All Svix entities have IDs as their unique identifiers. Some entities, such as applications and endpoints, support an additional unique identifier called `UID`.

These `UID`s can be used interchangeably with `ID`s all throughout the API. So for example, you can send a message to a specific `ID`, or a specific `UID`, both will work.

This enables you to use Svix in a completely stateless manner, without having to store the Svix identifiers (or anything) in your own database.


## Consumer Applications

When sending messages using the Svix API you will be sending them to a specific application (consumer), which will then distribute them to the associated endpoints.
In most cases you would want to create one application for each of our customers, though in some cases you may want to create multiple applications per customer.

Each application lies within its own security context. Each application is completely isolated from another, but also there is no isolation within an application. This means that you should assume that every message sent to an application can be viewed by all of the endpoints subscribed to that application. What does this mean in practice? Create different applications for different security contexts.

You can define a `uid` for an application which can then be used interchangeably in the API with the application's `id`. Most people set the `uid` to their own internal customer id, so for example if they have a user called `some-user` they would set the `uid` to `some-user` and then use it with the Svix API as follows:

```javascript
svix.application.update('some-user', ApplicationIn(/* ... */))
```

It's recommended to create an application (using the API) for each of their customers when they sign up to your service. You can however also create it "lazily", and only do it when they enable webhooks.

Alternatively, you can create an application the first time you send a message to it. When sending a message you can, optionally, send an `application` property along with it. If the application does not exist yet it will be created; if it does then the `application` property will be ignored.

```javascript
svix.message.create('some-user', {
    application: ApplicationIn(/* ... */),
    payload: {/* ... */},
})
```


## Endpoints

Endpoints represent a target for messages sent to a specific application. You can have multiple endpoints per application, and every message sent to the application will be sent to all of them. Endpoints can have filters applied to them which will prevent them from receiving specific messages. The most common such filter is [event type](event-types.mdx), where an endpoint can choose to only subscribe to a limited set of events.

Endpoints can be created by you using [the create endpoint API](https://api.svix.com/docs#operation/create_endpoint_api_v1_app__app_id__endpoint__post), though they are most commonly created by your customers using the [application portal](app-portal.mdx) or a similar UI.

Like with applications, you can define a `uid` for an endpoint which can then be used interchangeably in the API with the endpoint's `id`.


## Messages

Messages are the webhooks being sent. They can have a content, event type, and a few other properties.

A message sent to an application will be sent to all of its endpoints (based on aforementioned filtering rules).
When an application has no endpoints, or when no endpoints match a message, the sent message is just saved to the database but is not actually sent to a customer.

If a message delivery fails, it will be attempted multiple times until either it succeeds, or its attempts have been exhausted. Please refer to the [retry schedule](retries.mdx) for more information.

Messages can have an associated `eventId`. The `eventId` is used to map a message from Svix to one in your system so you can easily map a message to the reason why you sent it.


## Attempts

Attempts represent an attempt that has been made to send a message to an endpoint. Attempts also record the response content of the attempt, the response HTTP status code, as well as other properties. Each attempt to send a message is recorded in an attempt entity which can then be queried (there can be multiple when there are failures).


## Event Types

Event types are identifiers on messages that describe the message being sent and implies its associated schema. Each message has exactly one event type, and endpoints can listen to all, or a subset of the created event types.

Event types schemas are used for things like "send example webhook" in the application portal, the event catalog, and the [automatic Zapier integration](integrations/zapier.mdx).

You will need to create event types for them to be shown in the application portal and used by endpoints.


## Environments

Environments are completely isolated Svix environments that have their own API keys, data, and settings. You can think of Svix environments are completely separate accounts.

You can create as many environments as you want in the dashboard UI depending on your needs. Most people create one environment for `Production`, one for `Staging` and one for `Development`.
Some people create multiple `Production` environments based on geographical regions e.g. `Production EU` and `Production US`.


<!-- Source: https://docs.svix.com/play -->

---
title: Svix Play - Webhooks Debugger
---
# Svix Play - Webhooks Debugger


You can use the [Svix Play webhook playground and debugger](https://www.svix.com/play/) to easily inspect, test and debug operational webhooks.

It's a very useful tool for anyone developing webhooks - for both senders and consumers. More so, it's available to everyone for free, not just users of Svix. No signup required!

## How to use

To use Svix Play, just go to [play.svix.com](https://play.svix.com)

You'll be redirected to the main Svix Play page, where you can copy your unique webhook URL and start sending it requests. Every request sent to this URL will respond with a successful `200 OK` response, and will be visible in the UI for you to inspect.

This is how it looks like:

![Svix Play](/img/svix-play.png)

## Relay mode (Svix CLI)

In relay mode, you can use the Svix CLI for a free and secure public URL that relays requests to your local development server. All of these requests are then viewable in the [Svix Play webhook debugger](https://www.svix.com/play/) UI.

All you have to do is install the [Svix CLI](https://github.com/svix/svix-cli) and run `svix listen` as shown here:

```
$ svix listen http://localhost:8080/webhook/

Webhook relay is now listening at
https://play.svix.com/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/

All requests on this endpoint will be forwarded to your local URL:
http://localhost:8080/webhook/
```

## Advanced usage

### Custom response codes

Under normal usage, Svix Play (in echo mode) automatically returns successful responses to every request with the HTTP response code `200 OK`.

However, in some cases you may want to check how your webhook system responds to failures. For example, does auto-retry work? Are errors properly handled?

To enable that, Svix Play supports returning custom error codes by using the `force_status_code` query parameter when using our public API.

For example, if your URL was:

```
https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/
```

You can change it to the following URL in order to make it always return `404 Not Found`:

```
https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/?force_status_code=404
```

### Echo Request Bodies

Under normal usage, Svix Play will return an empty body to every request towards an `/in/` route.

If you wish to have the request body echoed back instead, set the `echo_body` query parameter to `true` when using our public API.

For example, if your URL was:

```
https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/
```

You can change it to the following URL to make it respond with the same body it was given.

```
https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/?echo_body=true
```

### Random Failure Rate

Svix Play supports simulating random failures to help you test how your webhook system handles intermittent issues. This is useful for testing retry logic, error handling, and system resilience.

You can use the `random_failure_rate` query parameter to specify a percentage (0-100) of requests that should randomly fail. When a request fails, it will use the status code from `force_status_code` if provided, or default to `400 Bad Request` if not set.

For example, if your URL was:

```
https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/
```

You can change it to the following URL to make 30% of requests fail with a `400 Bad Request`:

```
https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/?random_failure_rate=30
```

Or combine it with `force_status_code` to use a specific error code for the failures:

```
https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/?random_failure_rate=30&force_status_code=503
```

This will make 30% of requests fail with a `503 Service Unavailable` status.

### Programmatic Use of the Public API

To automatically test webhooks in your test suite, it is possible to use the public API to record dispatched webhooks and to see the history for a given token.

You will need an echo token to start. These tokens are freely generated and are simply used to distinguish active sessions. These tokens are the same as you would see when visiting the Svix Play [web application](https://play.svix.com). Such a token may be easily generated programmatically with a POST request to the following route:

```
https://api.play.svix.com/api/v1/token/generate/
```

Next, send any number of events to the following route with any HTTP method:

```
https://api.play.svix.com/api/v1/in/{your token here}/
```

This route can take the query parameters `force_status_code`, `random_failure_rate`, `echo_body`, and `endpoint_signing_key`.

Next, you'll want to analyze the record of events for this token using the `/history/` route as follows:

```
https://api.play.svix.com/api/v1/history/{your token here}/
```

The output of this route will look something like this:

```
{
  "iterator": "2Nmzzn6O30LTlFwegZYjrIEuRPL",
  "data": [
    {
      "id": "2Nmzzn6O30LTlFwegZYjrIEuRPL",
      "url": "/api/v1/in/e_DCFOA2693TG8wtcRLDaD8aFOm3J/",
      "method": "GET",
      "created_at": "2023-03-31T17:38:29.921531707Z",
      "body": "",
      "headers": {
        "accept": "*/*",
        "user-agent": "curl/7.81.0"
      },
      "response": {
        "status_code": 204,
        "headers": {},
        "body": ""
      },
      "ip": null
    }
  ]
}
```


This route allows one query parameter, `iterator`. Given the `id` of one of the events sent, the history route will only return events that were received after that ID.

For ease of use, the JSON object returned by the `/history/` route includes an `iterator` field which is set to the ID of the last received request, or the same iterator as given if no additional requests since then have been recorded.

For example, if your URL was:

```
https://api.play.svix.com/api/v1/history/e_94XdF-OwN3EaTKty4izJDWRAH3V/
```

You can change it to the following URL in order to only display events that were received after the request with ID `2Nvo8F66yxe0cT7lrVmsbUg97He`:

```
https://api.play.svix.com/api/v1/history/e_94XdF-OwN3EaTKty4izJDWRAH3V/?iterator=2Nvo8F66yxe0cT7lrVmsbUg97He
```

### Deleting History

You can delete all recorded events for a given token by making a DELETE request to the `/history/` route:

```
curl -X DELETE https://api.play.svix.com/api/v1/history/e_94XdF-OwN3EaTKty4izJDWRAH3V/
```

This will permanently remove all events associated with that token.


<!-- Source: https://docs.svix.com/quickstart -->

---
title: Quickstart
---
# Quickstart

Learn how to send your first webhook using Svix.

<AgentSkillsCallout />

## How Svix works

Svix acts as your webhook sending infrastructure and enables your customers to subscribe to events to power their integrations and workflow automations. You send Svix webhook messages using a single API call, and Svix then ensures reliable, low latency delivery to your customers' endpoints, handling retries, scaling, security, observability, and much more.

Additionally, Svix offers a [white-labeled embeddable portal](app-portal.mdx), allowing your customers to self-manage their own webhook endpoints, subscriptions, delivery rates, and more.

![How Svix works](/img/how-svix-works.svg)

### Core concepts

Svix is composed of three core building blocks: `applications`, `endpoints`, and `messages`.

[`Messages`](overview.mdx#messages) are the webhook messages being sent. They are most commonly JSON but Svix supports a variety of additional formats.

[`Applications`](overview.mdx#consumer-applications) (aka consumer applications) are where messages are sent to. You would usually have one application for each one of your customers , which depending on your product would mean you will have dozens, hundreds of thousands, or more applications in your account. Applications are isolated between one another, ensuring that your customers only have access to their subscriptions and data.

Most people create an application programmatically when a new customer is created on their platform. However, you can alternatively create the application when a customer enables webhooks, or have Svix create these automatically for you (more on that later).

[`Endpoints`](overview.mdx#endpoints) are essentially the URLs messages will be sent to. Each application can have multiple `endpoints` and each message sent to that application will be sent to all of them (based on the [event type](event-types.mdx) and other filtering rules).

Endpoints are usually managed directly by your customers using the Consumer Application Portal (more on that below).

### Information flow

Messages are created in your backend. They are usually created among other business logic, when the event occurs. They are then either sent to Svix directly, or are first sent to an internal event system (SQS, GCP Pub/Sub, Kafka, etc.) which then sends to Svix.

A message is sent to a specific consumer application and then Svix fans them out to all of the endpoints configured for that application.

![Information flow graph](/img/msg-flow-2.svg)

## Prerequisites

### Create an API key

Get your authentication token (`AuthToken`) from the [Svix dashboard](https://dashboard.svix.com).

To interact with the Svix service, you'll need an API key.
You can create one on the [API Access page](https://dashboard.svix.com/api-access) in the Svix dashboard.

![API Access page](/img/api-access-page.png)

### Install the Svix SDK (optional)

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
npm install svix
// Or
yarn add svix
```

</TabItem>
<TabItem value="Python">

```shell
pip install svix
```

</TabItem>
<TabItem value="Rust">

```toml
cargo add svix
```

</TabItem>
<TabItem value="Go">

```shell
go get github.com/svix/svix-webhooks/go
```

</TabItem>
<TabItem value="Java">

Gradle: Add this dependency to your project's build file:

```groovy
implementation "com.svix:svix:0.x.y"
```

Maven: Add this dependency to your project's POM:

```xml
<dependency>
  <groupId>com.svix</groupId>
  <artifactId>svix</artifactId>
  <version>0.x.y</version>
</dependency>
```

</TabItem>
<TabItem value="Kotlin">

Gradle: Add this dependency to your project's build file:

```groovy
implementation "com.svix.kotlin:svix-kotlin:0.x.y"
```

Maven: Add this dependency to your project's POM:

```xml
<dependency>
  <groupId>com.svix.kotlin</groupId>
  <artifactId>svix-kotlin</artifactId>
  <version>0.x.y</version>
</dependency>
```

</TabItem>
<TabItem value="Ruby">

```sh
gem install svix
```

</TabItem>
<TabItem value="C#">

```shell
dotnet add package Svix
```

</TabItem>
<TabItem value="PHP">

```shell
composer require svix/svix
```

</TabItem>
<TabItem value="CLI">

On macOS install via <a href="https://brew.sh/">Homebrew</a>:

```sh
brew install svix/svix/svix-cli
```

On Windows install via <a href="https://scoop.sh/">Scoop</a>:

```sh
scoop bucket add svix https://github.com/svix/scoop-svix.git
scoop install svix
```

For other platforms, such as linux, checkout the <a href="https://github.com/svix/svix-cli#installation">CLI docs</a> on Github.

</TabItem>
<TabItem value="cURL">

```shell
# Install cURL. E.g. on arch linux:
pacman -S curl
# Or on macOS
brew install curl
```

</TabItem>
</CodeTabs>

## Create a consumer application

As [mentioned above](#how-svix-works), consumer applications are where webhooks are sent to, and each one of your customers should have their own application.

Every entity on Svix supports setting a `uid` (user defined ID) which can then be used interchangeably with the Svix IDs throughout the APIs. This means that you can use your own identifiers in Svix, and you don't need to store any Svix identifiers on your end. Most people use their internal customer identifiers as the Svix `uid`s.

In this example, we'll show how to create an application with the `example-customer-123` UID using the [create application API endpoint](https://api.svix.com/docs#operation/create_application_api_v1_app__post), though in practice you will set it to whatever unique identifier you use in your database.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
const app = await svix.application.create({
  name: "Application name",
  uid: "example-customer-123"
});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, ApplicationIn

svix = Svix("AUTH_TOKEN")
app = svix.application.create(ApplicationIn(
    name="Application name",
    uid="example-customer-123"
))
```

</TabItem>
<TabItem value="Rust">

```rust
use svix::api::{ApplicationIn, Svix, SvixOptions};

let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let app = svix
    .application()
    .create(
        ApplicationIn {
            name: "Application name".to_string(),
            uid: Some("example-customer-123".to_string()),
            ..ApplicationIn::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
app, err := svixClient.Application.Create(ctx, &svix.ApplicationIn{
    Name: "Application name",
    Uid:  "example-customer-123",
})
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.models.ApplicationIn;
import com.svix.models.ApplicationOut;
import com.svix.Svix;

Svix svix = new Svix("AUTH_TOKEN");
ApplicationOut app = svix.getApplication().create(
    new ApplicationIn().name("Application name").uid("example-customer-123")
);
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.models.ApplicationIn
import com.svix.kotlin.models.ApplicationOut
import com.svix.kotlin.Svix

val svix = Svix("AUTH_TOKEN")
val applicationOut = svix.application.create(
    ApplicationIn(name = "Application name", uid = "example-customer-123")
)
```

</TabItem>
<TabItem value="Ruby">

```ruby
require "svix"

svix = Svix::Client.new("AUTH_TOKEN")

application_out = svix.application.create(Svix::ApplicationIn.new({
    "name" => "Application name",
    "uid" => "example-customer-123"
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN");
applicationOut = await svix.Application.CreateAsync(
    new ApplicationIn(name: "Application name", uid: "example-customer-123")
);
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$app = $svix->application->create(
  ApplicationIn::create(
    name: 'Application name'
  )->withUid('example-customer-123')
);
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'
svix application create '{ "name": "Application name", "uid": "example-customer-123" }'
```

</TabItem>
<TabItem value="cURL">

```shell
# Change URL based on your selected region
curl -X POST "https://api.us.svix.com/api/v1/app/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer AUTH_TOKEN" \
    -d '{"name": "Application name", "uid": "example-customer-123"}'
```

</TabItem>
</CodeTabs>


## Send a message

When you send a message in Svix you have to specify who you want to send it to, which means choosing a specific application (one of your customers).

In addition to the application, people also set the following properties when sending messages:

- `eventType`: an identifier denoting the type of the event. You can read more about event types in [the event type docs](event-types.mdx), but for this example we'll just use `invoice.paid` as the type.
- `eventId`: an optional unique ID for the event (unique per app). This is useful if you want to map each message to unique events on your system.
- `payload`: a JSON dictionary that can hold anything. Its content will be sent as the webhook content (Svix also supports sending non-JSON payloads).


This example uses the [create message API](https://api.svix.com/docs#operation/create_message_api_v1_app__app_id__msg__post) and the application we created in the previous step (`uid = example-customer-123`):

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
const svix = new Svix("AUTH_TOKEN");
await svix.message.create("example-customer-123", {
  eventType: "invoice.paid",
  eventId: "evt_Wqb1k73rXprtTm7Qdlr38G",
  payload: {
    type: "invoice.paid",
    id: "invoice_WF7WtCLFFtd8ubcTgboSFNql",
    status: "paid",
    attempt: 2,
  },
});
```

</TabItem>
<TabItem value="Python">

```python
svix = Svix("AUTH_TOKEN")
svix.message.create(
    "example-customer-123",
    MessageIn(
        event_type="invoice.paid",
        event_id="evt_Wqb1k73rXprtTm7Qdlr38G",
        payload={
            "type": "invoice.paid",
            "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status": "paid",
            "attempt": 2
        }
    )
)
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
svix.message()
    .create(
        "example-customer-123".to_string(),
        MessageIn {
            event_type: "invoice.paid".to_string(),
            event_id: Some("evt_Wqb1k73rXprtTm7Qdlr38G".to_string()),
            payload: json!({
                "type": "invoice.paid",
                "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
                "status": "paid",
                "attempt": 2
            }),
            ..MessageIn::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
svixClient := svix.New("AUTH_TOKEN", nil)
eventId := "evt_Wqb1k73rXprtTm7Qdlr38G"
svixClient.Message.Create(ctx, "example-customer-123", &svix.MessageIn{
    EventType: "invoice.paid",
    EventId: *svix.NullableString(&eventId),
    Payload: map[string]interface{}{
        "type":    "invoice.paid",
        "id":      "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        "status":  "paid",
        "attempt": 2,
    },
})
```

</TabItem>
<TabItem value="Java">

```java
Svix svix = new Svix("AUTH_TOKEN");
svix.getMessage().create("example-customer-123",
  new MessageIn()
    .eventType("invoice.paid")
    .eventId("evt_Wqb1k73rXprtTm7Qdlr38G")
    .payload("{" +
       "\"type\": \"invoice.paid\"," +
       "\"id\": \"invoice_WF7WtCLFFtd8ubcTgboSFNql\"," +
       "\"status\":  \"paid\"," +
       "\"attempt\": 2" +
      "}"));
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val svix = Svix("AUTH_TOKEN")
svix.message.create("example-customer-123",
        MessageIn(
            eventType = "invoice.paid",
            payload = mapOf<String, Any>(
                "type" to "invoice.paid",
                "id" to "invoice_WF7WtCLFFtd8ubcTgboSFNql",
                "status" to "paid",
                "attempt" to 2
            ),
            eventId = "evt_Wqb1k73rXprtTm7Qdlr38G"))
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
svix.message.create("example-customer-123",
    Svix::MessageIn.new({
        "event_type" => "invoice.paid",
        "payload" => {
            "type": "invoice.paid",
            "id" => "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status" => "paid",
            "attempt" => 2
        },
        "event_id" => "evt_Wqb1k73rXprtTm7Qdlr38G"}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN");
await svix.Message.CreateAsync("example-customer-123", new MessageIn(
    eventType: "invoice.paid",
    payload: new {
        type = "invoice.paid",
        id = "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        status = "paid",
        attempt = 2
    },
    eventId: "evt_Wqb1k73rXprtTm7Qdlr38G"
));
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$svix->message->create(
  'example-customer-123',
  MessageIn::create(
    eventType: 'invoice.paid',
    payload: [
      'type' => 'invoice.paid',
      'id' => 'invoice_WF7WtCLFFtd8ubcTgboSFNql',
      'status' => 'paid',
      'attempt' => 2
    ]
  )->withEventId('evt_Wqb1k73rXprtTm7Qdlr38G'),
);

```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN="AUTH_TOKEN"
svix message create example-customer-123 '{ "eventType": "invoice.paid", "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G", "payload": { "type": "invoice.paid", "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status": "paid", "attempt": 2 } }'
```

</TabItem>
<TabItem value="cURL">

```shell
# Change URL based on your selected region
curl -X POST "https://api.us.svix.com/api/v1/app/example-customer-123/msg/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer AUTH_TOKEN" \
    -d '{"eventType": "invoice.paid", "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G", "payload": {"type": "invoice.paid", "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status": "paid", "attempt": 2}}'
```

</TabItem>
</CodeTabs>

#### Including the event type in the payload

Webhook consumers often consume multiple event types using the same endpoint. To enable them to be able to differentiate different events, it's common practice to include the event type in the webhook's payload.
Svix, however, doesn't automatically inject the event type into the payload, in order to give our customers full control over the content and structure of the payloads they send.

Most commonly people include the event type in the payload as a top-level key called `type`, `event_type`, or `eventType`, but it's up to you how you want to call it.

#### Idempotency

Svix supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

For more information, please refer to the [idempotency section](./idempotency.mdx) of the docs.

Note: while the `eventId` can potentially be used to enforce short-term uniqueness (similar to idempotency), it's recommended to use the idempotency mechanism when needed rather than relying on `eventId` checks.


## Subscribe your customers to webhooks

In the example above we showed how to send messages, though these messages were not sent to any specific URLs. In order for them to be sent, we need to add endpoints. This is what this section is about.

<Callout type="default">

You can use the [Svix Play webhook debugger](https://www.svix.com/play/) and the [Svix CLI](https://github.com/svix/svix-cli) to inspect, test and debug your webhooks during development.

</Callout>
### Using the Application Portal

Svix offers a pre-built application portal. With one API call, you can give your users access to this UI and they can then add their own endpoints themselves. The UI can be embedded in your own dashboard and customized to match your dashboard's look-and-feel.

App portal access is based on short-lived sessions using special magic links. Your customers don't need a Svix account, and they don't even need to know that Svix exists.

You can read more about the app portal in the [application portal docs](./app-portal.mdx).

![embedded iframe screen](/img/app-portal/embedded-view-screen.png)


### Using the API

The app portal is built using the Svix SDKs, which means that everything you can do in the app portal you can also do using the Svix API. This includes creating endpoints.

Here is an example creating an endpoint using the [create endpoint API](https://api.svix.com/docs#operation/create_endpoint_api_v1_app__app_id__endpoint__post), and the application we created above (`uid = example-customer-123`):

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
const svix = new Svix("AUTH_TOKEN");
await svix.endpoint.create("example-customer-123", {
  url: "https://api.example.com/svix-webhooks/",
  description: "My main endpoint",
});
```

</TabItem>
<TabItem value="Python">

```python
svix = Svix("AUTH_TOKEN")
svix.endpoint.create(
    "example-customer-123",
    EndpointIn(
        url="https://api.example.com/svix-webhooks/",
        description="My main endpoint",
    )
)
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
svix.endpoint()
    .create(
        "example-customer-123".to_string(),
        EndpointIn {
            url: "https://api.example.com/svix-webhooks/".to_string(),
            description: Some("My main endpoint".to_string()),
            ..EndpointIn::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
svixClient := svix.New("AUTH_TOKEN", nil)
svixClient.Endpoint.Create(ctx, "example-customer-123", &svix.EndpointIn{
    Url:         "https://api.example.com/svix-webhooks/",
    Description: svix.String("My main endpoint"),
})
```

</TabItem>
<TabItem value="Java">

```java
Svix svix = new Svix("AUTH_TOKEN");
svix.getEndpoint()
    .create("example-customer-123",
            new EndpointIn()
              .url("https://api.example.com/svix-webhooks/")
              .description("My main endpoint"));
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val svix = Svix("AUTH_TOKEN")
val endpointOut =
    svix.endpoint.create("example-customer-123",
        EndpointIn(
            url = URI("https://api.example.com/svix-webhooks/"),
            description = "My main endpoint"))
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
endpoint_out =
    svix.endpoint.create("example-customer-123",
        Svix::EndpointIn.new({
            "url" => "https://api.example.com/svix-webhooks/",
            "description" => "My main endpoint"}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN");
endpointOut = await svix.Endpoint.CreateAsync(new EndpointIn(
    url: "https://api.example.com/svix-webhooks/",
    description: "My main endpoint"
));
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$endpointOut = $svix->endpoint->create(
  'example-customer-123',
  EndpointIn::create(
    url: 'https://api.example.com/svix-webhooks/',
  )->withDescription('My main endpoint')
);
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN="AUTH_TOKEN"
svix endpoint create example-customer-123 '{ "url": "https://api.example.com/svix-webhooks/", "description": "My main endpoint" }'
```

</TabItem>
<TabItem value="cURL">

```shell
# Change URL based on your selected region
curl -X POST "https://api.us.svix.com/api/v1/app/example-customer-123/endpoint/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer AUTH_TOKEN" \
    -d '{"url": "https://api.example.com/svix-webhooks/", "description": "My main endpoint"}'
```

</TabItem>
</CodeTabs>

Additionally, you can expose the API to your customers by creating equivalent API endpoints in your API, and making calls to the Svix API internally. For more on this, please reference the [exposing the API to your customers tutorial](./tutorials/api-webhook-management.md).


## Further reading

### Consuming webhooks documentation

Please refer to the [consuming webhooks](./consuming-webhooks.mdx) section for information you can share with your customers on how to easily consume webhooks, and how to use the application portal.


### Common Usage Examples

The above should give you everything you need to know in order to get started with Svix. However, we've gathered examples of some of the more common ways people use the Svix API in order to make it even easier for you to get started and follow the best practices.

For more information please refer to the [common usage examples section](./common-usage-examples.mdx).

### Custom server URL

The Svix libraries automatically infer the correct server URL from the authentication token, so setting a server URL is not necessary unless you are self-hosting the Svix server (open-source or Enterprise self-hosting).

This is how you override the server URL in each of the libraries:

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN", { serverUrl: "THE_SERVER_URL" });
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, SvixAsync, SvixOptions

svix = Svix("AUTH_TOKEN", SvixOptions(server_url="THE_SERVER_URL"))

# Or use the async variants
svix = SvixAsync("AUTH_TOKEN", SvixOptions(server_url="THE_SERVER_URL"))
```

</TabItem>
<TabItem value="Rust">

```rust
use svix::api::{ApplicationIn, Svix, SvixOptions};

let svix = Svix::new("AUTH_TOKEN".to_string(), SvixOptions {
    server_url: "THE_SERVER_URL".to_string(),
    ..SvixOptions::default()
});
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

serverUrl, _ := url.Parse("THE_SERVER_URL")
svixClient := svix.New("AUTH_TOKEN", &svix.SvixOptions{
	ServerUrl: serverUrl,
})
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.Svix;

Svix svix = new Svix("AUTH_TOKEN", new SvixOptions().serverUrl("THE_SERVER_URL"));
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Svix;

val svix = Svix("AUTH_TOKEN", SvixOptions("THE_SERVER_URL"))
```

</TabItem>
<TabItem value="Ruby">

```ruby
require "svix"

svix = Svix::Client.new("AUTH_TOKEN", Svix::SvixOptions.new(false, "THE_SERVER_URL"))
```

</TabItem>
<TabItem value="C#">

```csharp
using Svix;

var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("THE_SERVER_URL"));
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN', new SvixOptions(
    serverUrl: 'THE_SERVER_URL'
));
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'
export SVIX_SERVER_URL='THE_SERVER_URL'
svix application create '{ "name": "Application name" }'
```

</TabItem>
<TabItem value="cURL">

```shell
# Just replace the URL below
curl -X POST "https://api.us.svix.com/api/v1/app/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer AUTH_TOKEN" \
    -d '{"name": "Application name"}'
```

</TabItem>
</CodeTabs>

## Closing words

That's it! There are only three API calls you should really care about. Creating applications (i.e. users), sending messages, and giving your users access to the App Portal. All of them are covered here.


<!-- Source: https://docs.svix.com/receiving/additional-authentication -->

---
title: Additional Authentication
---
# Additional Authentication


Svix [signs all webhooks](./verifying-payloads/why.mdx) in order to ensure the security and authenticity of all of the webhooks being sent.

This security mechanism is already sufficient (and better) than other methods such as [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), and using an authentication token. However, some systems and IT departments have varying requirements for any HTTP request hitting their services (including webhooks), so Svix has built in support for these additional authentication modes.

## HTTP Basic Authentication

HTTP Basic Authentication (Basic Auth), is a common way of sending a server a pair of username and password, or more often a username and auth token. While there are different ways of passing these credentials, the simplest and most common way is by including it as part of the URL.

You can add it to the URL by prefixing the URL with the username and password (or token) and the @ symbol as such:

```
https://USERNAME:PASSWORD@example.com/webhook/
```

## Header based authentication

Some services require specific headers to be passed in order to be processed by their load balancers or application servers. These services often require a specific authentication token passed in the `Authorization` header, but sometimes there could also be different headers and values.

Svix supports setting custom headers to be sent for each endpoint both [using the API](https://api.svix.com/docs#operation/update_endpoint_headers_api_v1_app__app_id__endpoint__endpoint_id__headers__put) and using [the application portal](./using-app-portal/adding-endpoints.mdx).

## Firewalls (IP blocking)

Many, often larger, organizations have strict firewall rules for which IPs are allowed to send traffic to their systems. While this is not a very strong security mechanism on its own, it's often useful when used in conjunction with other methods (such as webhook signatures).

In order to support these organizations and their requirements, Svix only sends webhooks requests from a specific set of IPs as detailed in the [source IP addresses section](./source-ips.mdx).


<!-- Source: https://docs.svix.com/receiving/delivery-control -->

---
title: Delivery Control
---

# Delivery Control

If you want to dynamically control future webhook delivery to an endpoint from the receiving end,
Svix will respect the following HTTP header instructions in the webhook response:

- `webhook-delivery: disable` – disables the webhook endpoint,
  i.e. future messages sent to the application will not be delivered to it
- `webhook-delivery: abort-message` – stops retries of the message just sent;
  has no effect when the message wouldn't be retried anyways,
  such as when delivery is considered successful
  (for details about retries, see [Retry Schedule](/retries.mdx))


<!-- Source: https://docs.svix.com/receiving/introduction -->

---
title: Introduction
---
# Introduction


Read the following sections to learn why and how to verify webhooks sent by the Svix service and its customers.

<Callout type="default">

You can use the [Svix Play webhook debugger](https://www.svix.com/play/) and the [Svix CLI](https://github.com/svix/svix-cli) to inspect, test and debug your webhooks during development.

</Callout>
## Webhooks Consumption 101

Webhooks are how services notify each other of events. At their core they are just a `POST` request to a pre-determined endpoint. The endpoint can be whatever you want, and you can just [add them from the UI](/receiving/using-app-portal/adding-endpoints). You normally use one endpoint per service, and that endpoint listens to all of the event types. For example, if you receive webhooks from Acme Inc., you can structure your URL like: `https://www.example.com/acme/webhooks/`.

The way to indicate that a webhook has been processed is by returning a `2xx` (status code `200-299`) response to the webhook message within a reasonable time-frame (15s with Svix). It's also important to disable `CSRF` protection for this endpoint if the framework you use enables them by default.

Another important aspect of handling webhooks is to verify the signature and timestamp when processing them. You can learn more about it in the [why verify section](/receiving/verifying-payloads/why).


<!-- Source: https://docs.svix.com/receiving/source-ips -->

---
title: Static Source IP Addresses
---

import sourceIps from '../../public/webhook-ips.json'

# Static Source IP Addresses

In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from Svix's static IP addresses.

This is the full list of IP addresses that webhooks may originate from grouped by the region of the sender. The list is also available as a JSON file: [webhooks-ips.json](/webhook-ips.json).

## Regions

The list of IP addresses below is grouped by the respective Svix region. The region where webhooks are sent from is the same as the region of respective environment. This means that all webhooks in the EU region will use the EU IP addresses below, all webhooks in the US region will use the US IP addressed below, and the same for every other region.

### US

<pre>
<code>
{sourceIps["us"].join("\n")}
</code>
</pre>

### EU

<pre>
<code>
{sourceIps["eu"].join("\n")}
</code>
</pre>

### Australia (Private region)

<pre>
<code>
{sourceIps["au"].join("\n")}
</code>
</pre>

### Canada (Private region)

<pre>
<code>
{sourceIps["ca"].join("\n")}
</code>
</pre>

<Callout type="info">

**Important**

Static source IPs are not guaranteed for all pricing tiers, please refer to [the pricing page](https://www.svix.com/pricing/) for more information.

</Callout>
## Webhook User Agent

Some systems may require to identify the User-Agent used by Svix in addition to the IP addresses. Requests from the Svix service, as well as self-hosted instances, may use different user-agent strings depending on the exact plan and configuration (usually `Svix-Webhooks/{server-version}` or `Webhooks/{server-version}`).

However, every webhook coming from the Svix hosted service (using the IP addresses above), will also include `sender-9YMgn` in order to enable easy identification of requests coming from the hosted service.

## Frequently Asked Questions

### How often do Svix's webhook source IP addresses change?

For existing customers, the source IPs do not change. Once your account is using a given set of regional IPs, we keep that set stable so we don't break your integration. We may add new IPs over time as we expand capacity, but those additions apply to new customers — your existing webhook sender IPs stay the same.

### How much advance notice do you give before changing webhook source IPs?

We don't change the source IPs for existing customers, so there's no rotation schedule or change-notification process to worry about. If that ever needed to change for an exceptional reason, we would notify affected customers well in advance via email and our changelog, but in practice this has not happened.

### Are static webhook source IPs available on all Svix pricing tiers?

Static source IPs are included on the Pro and Enterprise tiers. For the most up-to-date details, please refer to [the pricing page](https://www.svix.com/pricing/).


<!-- Source: https://docs.svix.com/receiving/using-app-portal/adding-endpoints -->

---
title: Adding Endpoints
---
# Adding Endpoints


In order to start listening to messages sent through Svix, you will need to configure your **endpoints**.

Adding an endpoint is as simple as providing a URL that you control and a list of **event types** that you want to
listen to.

![add endpoint](/img/app-portal/add-endpoint.png)

<Callout type="default">

**Svix Play**

If you don't have a URL or your service isn't quite ready to start receiving events just yet,
just press the **use Svix Play** button to have a unique URL generated for you.

You'll be able to view and inspect all operational webhooks sent to your Svix Play URL, making it
effortless to get started.

</Callout>
When configuring your endpoint, make sure to take a look at the [Event Catalog](./event-catalog) to see the
full descriptions of each endpoint as well as all the fields they send.

If you don't specify any event types, by default, your endpoint will receive all events, regardless of type.
This can be helpful for getting started and for testing, but we recommend changing this to a subset later on
to avoid receiving unexpected messages.


<!-- Source: https://docs.svix.com/receiving/using-app-portal/connecting-your-coding-agent -->

---
title: Connecting Your Coding Agent
---
# Connecting Your Coding Agent

You can connect a coding agent directly to your webhooks using [MCP](https://modelcontextprotocol.io).

## Connect your agent

<Steps>

### Open 'Settings' → 'MCP'

### Click 'Connect to MCP'

This generates an access token and opens a dialog with ready-to-paste setup steps. Pick your agent from the tabs and follow the steps there.

The token is only shown once, so copy it before closing the dialog.

### Check that your agent picked it up

Restart your agent if it was already running, then confirm the server is connected.

</Steps>

## What you can ask

Once connected, you can ask questions in plain language and let the agent do the digging:

- _"Why is the `invoice.paid` event failing?"_ — it searches the correct endpoint,  checks the endpoint's delivery stats, then the failed attempts and the exact response your handler returned.
- _"What does the payload for this event actually look like?"_ — it fetches a recent message and its JSON payload, so you can write your handler against the real thing.
- _"My handler was down for an hour — replay what it missed."_ — it recovers the endpoint from that point in time.
- _"Which endpoint is this message not reaching?"_ — it lists every endpoint the message was attempted against and how each one responded.


<Callout type="warning">

Resending, recovering, and updating a transformation are real actions: they send actual webhooks to your endpoints and change live configuration. Your agent should only do these when you ask it to, but review those tool calls before approving them, the same way you would any other agent action.

</Callout>

## Managing your token

Your tokens are listed in the **MCP** tab, redacted, with the date each was created and when it expires.

- **Tokens expire.** They're valid for 7 days by default.
- **Revoke a token whenever you want.** Open the token's menu and select **Expire**. Any agent using it loses access immediately.
- **Payloads reach your agent's model.** Anything the agent reads, including message payloads, is sent to the model provider behind your coding agent, so treat it the way you'd treat pasting a payload into that tool.


<!-- Source: https://docs.svix.com/receiving/using-app-portal/event-catalog -->

---
title: Event Catalog
---
# Event Catalog


The Event Catalog shows all the **event types** available to subscribe to.

![event catalog](/img/app-portal/event-catalog.png)

From here, you can view the **event definition**–the shape of the event payload
as well as what values you can expect to receive.

In addition, you can see an example payload for that event type.


<!-- Source: https://docs.svix.com/receiving/using-app-portal/filtering-logs -->

---
title: Filtering Logs
---
# Filtering Logs


![unfiltered message logs](/img/app-portal/log-list.png)

If you need to track down a particular message that was sent to one of your
endpoints, there are a few ways to help you find it.

If you know what endpoint it went to, the **endpoint page** has a filtered
list of all messages sent to it. You can filter this list by
**event type**. If you know roughly when the message was sent, you can further
narrow down the list using the **date filter**.

![date filter](/img/app-portal/date-filter.png)

You can choose to filter from one of the presets:

- 5 hours ago
- yesterday
- last week
- last month
- custom

If you choose "custom", you can specify an exact date and time to jump back to
in the message list.


<!-- Source: https://docs.svix.com/receiving/using-app-portal/polling-endpoints -->

---
title: Polling Endpoints
---
# Polling Endpoints


Polling Endpoints are a way to get a stream of events by polling, without having to set up a webhook endpoint.

Start by creating an endpoint and select *Polling Endpoint* as the type.

![Polling Endpoint Create](/img/advanced-endpoints/polling-endpoint-create.png)

As with [regular webhook endpoints](/receiving/using-app-portal/adding-endpoints), you can control which event types and channels you want to receive.


## Usage

Once you've created a Polling Endpoint, you'll get a unique URL like `https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/{consumer_id}`.

You can call this endpoint directly once you have an [API key](/receiving/using-app-portal/polling-endpoints#api-keys).

Poll this URL to receive messages for a given `Consumer ID`. Each consumer tracks its own progress independently.

```bash
curl \
  -X GET "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/MY_CONSUMER_ID" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer sk_poll_*****.eu'
```

Each message includes an `offset`. Messages are returned in the order they were received.

```json
{
  "data": [{
    "id": "msg_2K2N9Qk...",
    "eventType": "invoice.created",
    "payload": { "hello": "world" },
    "timestamp": "2025-01-17T00:00:00.000Z",
    "offset": 0
  }],
  "done": true
}
```

After processing a batch, commit the last message's `offset` so the next poll continues from there.

```bash
curl \
  -X POST "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/MY_CONSUMER_ID/commit" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_poll_*****.eu' \
  -d '{ "offset": 0 }'
```

Until you commit, the same messages may be returned again after the lease expires. Use a stable `Consumer ID` per worker so progress is preserved across restarts.

### API Keys

To call the Polling Endpoint, you'll need to create an endpoint-specific API key.


<div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', width: '100%', marginBottom: '2rem' }}>
<div style={{ width: '35%' }}>
  <img
    src="/img/advanced-endpoints/polling-endpoint-details-create-key.png"
    alt="Polling Endpoint Create API Key"
    style={{ objectFit: 'contain', boxShadow: '0 0' }}
  />
</div>
  <div style={{ width: '60%' }}>
  <img
    src="/img/advanced-endpoints/polling-endpoint-create-key.png"
    alt="Polling Endpoint Create API Key"
    style={{ objectFit: 'contain', boxShadow: '0 0' }}
  />
  </div>
</div>


API keys are scoped exclusively to the endpoint they were created for, and they can be expired or rotated at any time.

## Using AutoConfig

You can also create and manage Polling Endpoints with AutoConfig.

With AutoConfig, you can set event types and other configuration in code and AutoConfig will automatically ensure the settings are up to date.
Configuration automatically changes when your code changes without needing to go to the UI and reconfigure the endpoint.

When creating a Polling Endpoint, select **Use AutoConfig**. You'll get an AutoConfig token to use with the Svix SDK.

![AutoConfig token in the Application Portal](/img/autoconfig/autoconfig-token.png)

Use `AutoConfigConsumer` to configure the endpoint and poll for messages:

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP"]}>

<TabItem value="JavaScript">
```js
import { AutoConfigConsumer } from "svix";

const consumer = new AutoConfigConsumer(AUTO_CONFIG_TOKEN, {
  filterTypes: ["invoice.paid", "user.created"],
});

// Create or update the polling endpoint when your code changes
await consumer.subscribe();

// Inside a worker loop
const msgs = await consumer.receive("my-consumer");
// ... process msgs.data
await consumer.commit("my-consumer", msgs.data.at(-1).offset);
```
</TabItem>

<TabItem value="Python">
```python
from svix import AutoConfigConsumer
from svix.models import SinkInCommon

consumer = AutoConfigConsumer(
    AUTO_CONFIG_TOKEN,
    SinkInCommon(
        filter_types=["invoice.paid", "user.created"],
    ),
)

# Create or update the polling endpoint when your code changes
consumer.subscribe()

# Inside a worker loop
msgs = consumer.receive("my-consumer")
# ... process msgs.data
consumer.commit("my-consumer", msgs.data[-1].offset)
```
</TabItem>

<TabItem value="Rust">
```rust
let consumer = svix::AutoConfigConsumer::new(
    AUTO_CONFIG_TOKEN.to_string(),
    svix::SinkInCommon {
        filter_types: Some(vec![
            "invoice.paid".to_string(),
            "user.created".to_string(),
        ]),
        ..Default::default()
    },
)?;

// Create or update the polling endpoint when your code changes
consumer.subscribe().await?;

// Inside a worker loop
let msgs = consumer.receive("my-consumer".to_string(), None).await?;
// ... process msgs.data
let offset = msgs.data.last().unwrap().offset;
consumer.commit("my-consumer".to_string(), offset, None).await?;
```
</TabItem>

<TabItem value="Go">
```go
import (
	"context"
	svix "github.com/svix/svix-webhooks/go"
	"github.com/svix/svix-webhooks/go/models"
)

consumer, err := svix.NewAutoConfigConsumer(AUTO_CONFIG_TOKEN, models.SinkInCommon{
	FilterTypes: []string{"invoice.paid", "user.created"},
})
if err != nil {
	panic(err)
}

// Create or update the polling endpoint when your code changes
if _, err := consumer.Subscribe(ctx); err != nil {
	panic(err)
}

// Inside a worker loop
msgs, err := consumer.Receive(ctx, "my-consumer", nil)
if err != nil {
	panic(err)
}
// ... process msgs.Data
offset := msgs.Data[len(msgs.Data)-1].Offset
if err := consumer.Commit(ctx, "my-consumer", offset, nil); err != nil {
	panic(err)
}
```
</TabItem>

<TabItem value="Java">
```java
import com.svix.AutoConfigConsumer;
import com.svix.models.SinkInCommon;
import java.util.Set;

AutoConfigConsumer consumer = new AutoConfigConsumer(
    AUTO_CONFIG_TOKEN,
    new SinkInCommon()
        .filterTypes(Set.of("invoice.paid", "user.created")));

// Create or update the polling endpoint when your code changes
consumer.subscribe();

// Inside a worker loop
var msgs = consumer.receive("my-consumer");
// ... process msgs.getData()
long offset = msgs.getData().get(msgs.getData().size() - 1).getOffset();
consumer.commit("my-consumer", offset);
```
</TabItem>

<TabItem value="Kotlin">
```kotlin
import com.svix.kotlin.AutoConfigConsumer
import com.svix.kotlin.models.SinkInCommon

val consumer = AutoConfigConsumer(
    AUTO_CONFIG_TOKEN,
    SinkInCommon(
        filterTypes = setOf("invoice.paid", "user.created"),
    ),
)

// Create or update the polling endpoint when your code changes
consumer.subscribe()

// Inside a worker loop
val msgs = consumer.receive("my-consumer")
// ... process msgs.data
val offset = msgs.data.last().offset
consumer.commit("my-consumer", offset)
```
</TabItem>

<TabItem value="Ruby">
```ruby
require "svix"

sink = Svix::SinkInCommon.new(
  "filter_types" => ["invoice.paid", "user.created"],
)

consumer = Svix::AutoConfigConsumer.new(AUTO_CONFIG_TOKEN, sink)

# Create or update the polling endpoint when your code changes
consumer.subscribe

# Inside a worker loop
msgs = consumer.receive("my-consumer")
# ... process msgs.data
offset = msgs.data.last.offset
consumer.commit("my-consumer", offset)
```
</TabItem>

<TabItem value="C#">
```csharp
using Svix;
using Svix.Models;

var consumer = new AutoConfigConsumer(
    AUTO_CONFIG_TOKEN,
    new SinkInCommon
    {
        FilterTypes = new[] { "invoice.paid", "user.created" },
    });

// Create or update the polling endpoint when your code changes
await consumer.SubscribeAsync();

// Inside a worker loop
var msgs = await consumer.ReceiveAsync("my-consumer");
// ... process msgs.Data
var offset = msgs.Data[^1].Offset;
await consumer.CommitAsync("my-consumer", offset);
```
</TabItem>

<TabItem value="PHP">
```php
use Svix\AutoConfigConsumer;
use Svix\Models\SinkInCommon;

$consumer = new AutoConfigConsumer(
    AUTO_CONFIG_TOKEN,
    SinkInCommon::create()
        ->withFilterTypes(['invoice.paid', 'user.created']),
);

// Create or update the polling endpoint when your code changes
$consumer->subscribe();

// Inside a worker loop
$msgs = $consumer->receive('my-consumer');
// ... process $msgs->data
$offset = end($msgs->data)->offset;
$consumer->commit('my-consumer', $offset);
```
</TabItem>
</CodeTabs>

Calling `subscribe()` creates or updates the polling endpoint. In your worker, call `receive()` to fetch messages for a consumer, then `commit()` the last message's offset so the next poll continues from there.

The AutoConfig token is scoped to the endpoint it was created for, and can also be rotated at any time.


<!-- Source: https://docs.svix.com/receiving/using-app-portal/replaying-messages -->

---
title: Replaying Messages
---
# Replaying Messages


## Why Replay

- If your service has downtime
- If your endpoint was misconfigured

If you want to replay a single event, you can find the message
from the UI and click the options menu next to any of the attempts.

![resend message](/img/app-portal/resend-single.png)

From there, click "resend" to have the same message send to your
endpoint again.

If you need to recover from a service outage and want to replay all
the events since a given time, you can do so from the Endpoint page.
On an endpoint's details page, click `Options > Recover Failed Messages`.

![recover modal](/img/app-portal/replay-modal.png)

From there, you can choose a time window to recover from.

For a more granular recovery – for example, if you know the exact timestamp
that you want to recover from – you can click the options menu on any message
from the endpoint page. From there, you can click "Replay..." and choose to
"Replay all failed messages since this time."

---

With all the ways to resend and recover failed messages, you can be more
confident in your endpoints and free to experiment with new event types.


<!-- Source: https://docs.svix.com/receiving/using-app-portal/testing-events -->

---
title: Testing Events
---
# Testing Events


The easiest way to be more confident in your endpoint configuration
is to start receiving events as quickly as possible.

That's why we have a "Testing" tab for you to send example events
to your endpoint.

![testing endpoint](/img/app-portal/testing-endpoint.png)

After sending an example event, you can click into the message to view
the message payload, all of the message attempts, and whether it
succeeded or failed.


<!-- Source: https://docs.svix.com/receiving/verifying-payloads/how-manual -->

---
title: Verifying Webhooks Manually
---
# Verifying Webhooks Manually

<Callout type="info">

The recommended way to verify webhooks is using our official libraries as outlined in the [How to Verify](./how.mdx) section.

<ReceivingSkillCopy />

</Callout>
However, here are instructions for verifying manually for those who need it.

## Verifying signatures manually

Each webhook call includes three headers with additional information that are used for verification:

* `svix-id`: the unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is being resent (e.g. due to a previous failure).
* `svix-timestamp`: timestamp in [seconds since epoch](https://en.wikipedia.org/wiki/Unix_time).
* `svix-signature`: the [Base64](https://en.wikipedia.org/wiki/Base64) encoded list of signatures (space delimited).

<Callout type="info">

Professional and Enterprise tier customers can have the headers white-labeled to use the `webhook-` prefix instead of the `svix-` prefix used above. The Svix libraries support both.

</Callout>
### Constructing the signed content

The content to sign is composed by concatenating the id, timestamp and payload, separated by the full-stop character (`.`). In code, it will look something like:

```javascript
const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
```

Where `body` is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should *not* change the body in any way before verifying.

### Determining the expected signature

Svix uses an [HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2) to sign its webhooks.

So to calculate the expected signature, you should HMAC the `signed_content` from above using the base64 portion of your signing secret (this is the part after the `whsec_` prefix) as the key.
For example, given the secret `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw` you will want to use `MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`.

For example, this is how you can calculate the signature in Node.js:

```javascript
const crypto = require('crypto');

const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

// Need to base64 decode the secret
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
const signature = crypto
  .createHmac('sha256', secretBytes)
  .update(signedContent)
  .digest('base64');

console.log(signature);
```

This generated signature should match one of the ones sent in the `svix-signature` header.

The `svix-signature` header is composed of a list of space delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one. Though there could be any number of signatures. For example:

```
v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
```

Make sure to remove the version prefix and delimiter (e.g. `v1,`) before verifying the signature.

Please note that to compare the signatures it's recommended to use a constant-time string comparison method in order to prevent timing attacks.

### Verify timestamp

As mentioned above, Svix also sends the timestamp of the attempt in the `svix-timestamp` header. You should compare this timestamp against your system timestamp and make sure it's within your tolerance in order to prevent timestamp attacks.


### Example signatures

Here is an example you can use to verify you implemented everything correctly. Please note that this may fail verification due to the timestamp being old.

```javascript
secret = 'whsec_plJ3nmyCDGBKInavdOK15jsl';
payload = '{"event_type":"ping","data":{"success":true}}';
msg_id = 'msg_loFOjxBNrRLzqYUf';
timestamp = '1731705121';

// Would generate the following signature:
signature = 'v1,rAvfW3dJ/X/qxhsaXPOyyCGmRKsaKWcsNccKXlIktD0=';
```

Additionally, you can use the [webhook simulation tool](https://www.standardwebhooks.com/simulate) to generate as many examples as you need.


<!-- Source: https://docs.svix.com/receiving/verifying-payloads/how -->

---
title: How to Verify Webhooks with the Svix Libraries
---
# How to Verify Webhooks with the Svix Libraries

As shown in the [Why Verify section](./why.mdx), verifying operational webhooks is very important. This section describes how to do it.

<ReceivingSkillCallout />

## Verifying using our official libraries

First install the libraries if you haven't already:

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
npm install svix
// Or
yarn add svix
```

</TabItem>
<TabItem value="Python">

```sh
pip install svix
```

</TabItem>
<TabItem value="Rust">

```toml
http = "1.0.0"
svix = "1.20.0"
```

</TabItem>
<TabItem value="Go">

```shell
go get github.com/svix/svix-webhooks/go
```

</TabItem>
<TabItem value="Java">

Gradle: Add this dependency to your project's build file:

```groovy
implementation "com.svix:svix:0.x.y"
```

Maven: Add this dependency to your project's POM:

```xml
<dependency>
  <groupId>com.svix</groupId>
  <artifactId>svix</artifactId>
  <version>0.x.y</version>
</dependency>
```

</TabItem>
<TabItem value="Kotlin">

Gradle: Add this dependency to your project's build file:

```groovy
implementation "com.svix.kotlin:svix-kotlin:0.x.y"
```

Maven: Add this dependency to your project's POM:

```xml
<dependency>
  <groupId>com.svix.kotlin</groupId>
  <artifactId>svix-kotlin</artifactId>
  <version>0.x.y</version>
</dependency>
```

</TabItem>
<TabItem value="Ruby">

```shell
gem install svix
```

</TabItem>
<TabItem value="C#">

```shell
dotnet add package Svix
```

</TabItem>
<TabItem value="PHP">

```shell
composer require svix/svix
```

</TabItem>
<TabItem value="CLI">

On macOS install via <a href="https://brew.sh/">Homebrew</a>:
```sh
brew install svix/svix/svix-cli
```

On Windows install via <a href="https://scoop.sh/">Scoop</a>:
```sh
scoop bucket add svix https://github.com/svix/scoop-svix.git
scoop install svix
```

For other platforms, such as linux, checkout the <a href="https://github.com/svix/svix-cli#installation">CLI docs</a> on Github.

</TabItem>
<TabItem value="cURL">

```shell
# Install cURL. E.g. on arch linux:
pacman -S curl
```

</TabItem>
</CodeTabs>

Then verify webhooks using the code below. The payload is the raw (string) body of the request, and the headers are the headers passed in the request.

<Callout type="important">

**Use the raw request body**

You need to use the raw request body when verifying webhooks, as the cryptographic signature is sensitive to even the slightest changes.
You should watch out for frameworks that parse the request as JSON and then stringify it because this too will break the signature verification.

See examples below for how to get the raw request body with different frameworks.

</Callout>
The signature you should get from where you added the endpoint, e.g. the application portal.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
const headers = {
  "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp": "1614265330",
  "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
wh.verify(payload, headers);
```

</TabItem>
<TabItem value="Python">

```python
from svix.webhooks import Webhook

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

# These were all sent from the server
headers = {
  "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp": "1614265330",
  "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
}
payload = '{"test": 2432232314}'

wh = Webhook(secret)
# Throws on error, returns the verified content on success
wh.verify(payload, headers)
```

</TabItem>
<TabItem value="Rust">

```rust
use svix::webhooks::Webhook;

let secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw".to_string();

let mut headers = http::HeaderMap::new();
headers.insert("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek");
headers.insert("svix-timestamp", "1614265330");
headers.insert(
    "svix-signature",
    "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
);

let payload = b"{\"test\": 2432232314}";

let wh = Webhook::new(&secret)?;
wh.verify(&payload, &headers)?;
// returns Ok on success, Err otherwise
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

secret := "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

// These were all sent from the server
headers := http.Header{}
headers.Set("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek")
headers.Set("svix-timestamp", "1614265330")
headers.Set("svix-signature", "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=")

payload := []byte(`{"test": 2432232314}`)

wh, err := svix.NewWebhook(secret)
err := wh.Verify(payload, headers)
// returns nil on success, error otherwise
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.Webhook;

String secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
HashMap<String, List<String>> headerMap = new HashMap<String, List<String>>();
headerMap.put("svix-id", Arrays.asList("msg_p5jXN8AQM9LWM0D4loKWxJek"));
headerMap.put("svix-timestamp", Arrays.asList("1614265330"));
headerMap.put("svix-signature", Arrays.asList("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="));
HttpHeaders headers = HttpHeaders.of(headerMap, BiPredicate<String, String>)

String payload = "{\"test\": 2432232314}";

Webhook webhook = new Webhook(secret);

webhook.verify(payload, headers)
// throws WebhookVerificationError exception on failure.
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Webhook

val secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
val headersMap = mapOf(
    "svix-id" to listOf("msg_p5jXN8AQM9LWM0D4loKWxJek"),
    "svix-timestamp" to listOf("1614265330"),
    "svix-signature" to listOf("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=")
)
val headers = HttpHeaders.of(headersMap) { _, _ -> true }

val payload = "{\"test\": 2432232314}";

val webhook = Webhook(secret);

webhook.verify(payload, headers)
// throws WebhookVerificationError exception on failure.
```

</TabItem>
<TabItem value="Ruby">

```ruby
require 'svix'


# These were all sent from the server
headers = {
  "svix-id" => "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp" => "1614265330",
  "svix-signature" => "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="
}
payload = '{"test": 2432232314}'

wh = Svix::Webhook.new("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw")
# Raises on error, returns the verified content on success
json = wh.verify(payload, headers)
```

</TabItem>
<TabItem value="C#">

```csharp
using Svix;
using System.Net;

// These were all sent from the server
var headers = new WebHeaderCollection();
headers.Set("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek");
headers.Set("svix-timestamp", "1614265330");
headers.Set("svix-signature", "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=");
var payload = "{\"test\": 2432232314}";

var wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw/Je4ZJEGP1QFb");

// Throws on error
wh.Verify(payload, headers);
```

</TabItem>
<TabItem value="PHP">

```php
// import using composers autoload
require_once('vendor/autoload.php');
// or manually
require_once('/path/to/svix/php/init.php');

// These were all sent from the server
$payload = '{"test": 2432232314}';
$header = array(
        'svix-id'  => 'msg_p5jXN8AQM9LWM0D4loKWxJek',
        'svix-timestamp' => '1614265330',
        'svix-signature' => 'v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=',
    );

// Throws on error, returns the verified content on success
$wh = new \Svix\Webhook('whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw');
$json = $wh->verify($payload, $header);
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN="AUTH_TOKEN"
svix verify --secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw --msg-id msg_p5jXN8AQM9LWM0D4loKWxJek --timestamp 1614265330 --signature v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= '{"test": 2432232314}'
```

</TabItem>
<TabItem value="cURL">

No easy way to verify the signature just with cURL.

</TabItem>
</CodeTabs>


## Framework specific examples

Here are examples on how to adjust the above examples to your favourite framework!

### Python (Django)

```python
from django.http import HttpResponse

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@csrf_exempt
def webhook_handler(request):
    headers = request.headers
    payload = request.body

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return HttpResponse(status=400)

    # Do something with the message...

    return HttpResponse(status=204)
```

### Python (Flask)

```python
from flask import request

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@app.route('/webhook/')
def webhook_handler():
    headers = request.headers
    payload = request.get_data()

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        return ('', 400)

    # Do something with the message...

    return ('', 204)
```

### Python (FastAPI)

```python
from fastapi import Request, Response, status

from svix.webhooks import Webhook, WebhookVerificationError

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

@router.post("/webhook/", status_code=status.HTTP_204_NO_CONTENT)
async def webhook_handler(request: Request, response: Response):
    headers = request.headers
    payload = await request.body()

    try:
        wh = Webhook(secret)
        msg = wh.verify(payload, headers)
    except WebhookVerificationError as e:
        response.status_code = status.HTTP_400_BAD_REQUEST
        return

    # Do something with the message...
```

### Node.js (Next.js)

The [`svix-example`](https://github.com/svix/svix-example) repo contains an [example](https://github.com/svix/svix-example/blob/main/src/pages/api/consumer/webhooks.ts) of how to verify and use webhooks in a Next.js application.

```js
import { Webhook } from "svix";
import { buffer } from "micro";

export const config = {
    api: {
        bodyParser: false,
    },
}

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

export default async function handler(req, res) {
    const payload = (await buffer(req)).toString();
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
}
```

### Node.js (Next.js 13 App Router)

```js
import { Webhook } from "svix";

const webhookSecret: string = process.env.WEBHOOK_SECRET || "your-secret";

export async function POST(req: Request) {
  const svix_id = req.headers.get("svix-id") ?? "";
  const svix_timestamp = req.headers.get("svix-timestamp") ?? "";
  const svix_signature = req.headers.get("svix-signature") ?? "";

  const body = await req.text();

  const sivx = new Webhook(webhookSecret);

  let msg;

  try {
    msg = sivx.verify(body, {
      "svix-id": svix_id,
      "svix-timestamp": svix_timestamp,
      "svix-signature": svix_signature,
    });
  } catch (err) {
    return new Response("Bad Request", { status: 400 });
  }

  console.log(msg);

  // Rest

  return new Response("OK", { status: 200 });
}
```

### Node.js (Netlify Functions)

```js
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";


export const handler = async ({body, headers}) => {
    const payload = body;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
}
```


### Node.js (Express)

**Note:** When integrating this example into a larger codebase, you will have to
make sure not to apply the `express.json()` middleware to the webhook route,
because the payload has to be passed to `wh.verify` without any prior parsing.

```js
import { Webhook } from "svix";
import bodyParser from "body-parser";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

app.post('/webhook', bodyParser.raw({ type: 'application/json' }), (req, res) => {
    const payload = req.body;
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    try {
        msg = wh.verify(payload, headers);
    } catch (err) {
        res.status(400).json({});
    }

    // Do something with the message...

    res.json({});
});
```

### Node.js (NestJS)

Initialize the application with the `rawBody` flag set to true. See the (NestJS docs)[https://docs.nestjs.com/faq/raw-body#raw-body] for details.

```js
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(
    AppModule,
    { rawBody: true } // add rawBody flag
  );
  await app.listen(3000);
}
bootstrap();

```

```js
// webhook.controller.ts
import { Controller, Post, RawBodyRequest, Req } from '@nestjs/common';
import { Request } from 'express';
import { Webhook } from 'svix';

@Controller('webhook')
class WebhookController {
  @Post()
  webhook(@Req() request: RawBodyRequest<Request>) {
    const secret = 'whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw';
    const wh = new Webhook(secret);

    const payload = request.rawBody.toString('utf8');
    const headers = request.headers;

    let msg;
    try {
      msg = wh.verify(payload, headers);
    } catch (err) {
      // handle error
    }

    // Do something with the message...
  }
}

```

### Node.js (Nuxt)

```js
import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

export default defineEventHandler(async (event) => {
  const headers = getRequestHeaders(event);
  const payload = await readRawBody(event);

  const wh = new Webhook(secret);

  let msg;

  try {
      msg = wh.verify(payload, headers);
  } catch (err) {
      setResponseStatus(event, 400);
      return "Bad Request";
  }

  // Do something with the message...
  return "OK";
})
```

### Go (Standard lib)

```go
package main

import (
	"io"
	"log"
	"net/http"

	svix "github.com/svix/svix-webhooks/go"
)

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

func main() {

	wh, err := svix.NewWebhook(secret)
	if err != nil {
		log.Fatal(err)
	}

	http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
		headers := r.Header
		payload, err := io.ReadAll(r.Body)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		err = wh.Verify(payload, headers)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		// Do something with the message...

		w.WriteHeader(http.StatusNoContent)

	})
	http.ListenAndServe(":8080", nil)
}
```

### Go (Gin)

```go
package main

import (
	"io"
	"log"
	"net/http"

	"github.com/gin-gonic/gin"
	svix "github.com/svix/svix-webhooks/go"
)

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

func main() {

	wh, err := svix.NewWebhook(secret)
	if err != nil {
		log.Fatal(err)
	}

	r := gin.Default()
	r.POST("/webhook", func(c *gin.Context) {
		headers := c.Request.Header
		payload, err := io.ReadAll(c.Request.Body)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		err = wh.Verify(payload, headers)
		if err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		// Do something with the message...

		c.JSON(200, gin.H{})
	})
	r.Run()
}
```

### Rust (axum)

Add the `webhook_in` route below to an axum router.

```rust
use axum::{body::Bytes, http::StatusCode};
use hyper::HeaderMap;

pub const SECRET: &'static str = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

pub async fn webhook_in(headers: HeaderMap, body: Bytes) -> StatusCode {
    let Ok(wh) = svix::webhooks::Webhook::new(SECRET) else {
        return StatusCode::INTERNAL_SERVER_ERROR;
    };

    if let Err(_) = wh.verify(&body, &headers) {
        return StatusCode::BAD_REQUEST;
    }

    // Do something with the message...

    StatusCode::NO_CONTENT
}
```

### Ruby (Ruby on Rails)

Once you've set up your project add a route to your `config/routes.rb` file at the top of the `Rails.application.routes.draw` block:

```rb
Rails.application.routes.draw do
  post "/webhook", to: "webhook#index"

  # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
end
```

The route above declares that `POST /webhook` requests are mapped to the index action of `WebhookController`.

To create `WebhookController` and its index action, we'll run the controller generator (with the `--skip-routes` option because we already have an appropriate route):

```sh
bin/rails generate controller Webhook index --skip-routes
```

Rails will create several files for you:

```sh
    create  app/controllers/webhook_controller.rb
    invoke  erb
    create    app/views/webhook
    create    app/views/webhook/index.html.erb
    invoke  test_unit
    create    test/controllers/webhook_controller_test.rb
    invoke  helper
    create    app/helpers/webhook_helper.rb
    invoke    test_unit
    invoke  assets
    invoke    scss
    create      app/assets/stylesheets/webhook.scss
```

Now we can add our verification logic to the newly created `app/controllers/webhook_controller.rb` file:

```rb
require 'svix'

class WebhookController < ApplicationController
  protect_from_forgery with: :null_session # disables CSRF middleware; required for API endpoints

  def index
    begin
      payload = request.body.read
      headers = request.headers
      wh = Svix::Webhook.new("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw")

      json = wh.verify(payload, headers)

      # Do something with the message...

      head :no_content
    rescue
      head :bad_request
    end
  end
end
```

### PHP (Laravel)

In your `routes/api.php` file add the following after the last use directive:

```php
use Svix\Webhook;
use Svix\Exception\WebhookVerificationException;

Route::post('webhook', function(Request $request) {
    $payload = $request->getContent();
    $headers = collect($request->headers->all())->transform(function ($item) {
        return $item[0];
    });

    try {
        $wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw");
        $json = $wh->verify($payload, $headers);

        # Do something with the message...

        return response()->noContent();
    } catch (WebhookVerificationException $e) {
        return response(null, 400);
    }
});
```


<!-- Source: https://docs.svix.com/receiving/verifying-payloads/receiving-with-bridge -->

---
title: Receiving Webhooks with Bridge
---
# Receiving Webhooks with Bridge

[Svix Bridge] is useful in cases where you want to consume webhooks and write the payloads to a message queue.


## Using the Built-in HTTP Server

Since Bridge can act as an HTTP server, you can configure it as an Endpoint in Svix.
Bridge can even verify webhooks when configured with an `endpoint_secret`.

For example, receiving webhooks from Svix, lightly reshaping the payload, then publishing to RabbitMQ might be
configured like this:

```yaml
receivers:
  - name: 'events-from-acme'
    input:
      type: 'svix-webhook'
      path_id: 'acme'
      endpoint_secret: '${ENDPOINT_SECRET}'

    transformation: |
      function handler(input) {
        let event_type = input.eventType;
        delete input.eventType;
        // The `payload` field is what will be published to the queue.
        return { payload: { event_type, ...input } };
      }

    output:
      type: 'rabbitmq'
      uri: '${RABBITMQ_URI}'
      exchange: ''
      routing_key: 'acme'
```

The `path_id` defined here represents the trailing path segment for the route this receiver will match.
The route for this example would be `/webhook/acme` and sending a `POST` request here with a valid JSON body will result
in a new message published to the `acme` queue.

This is to say, if you're running Bridge at `https://my-bridge.example.com`, the full URL you'd register as a Svix
Endpoint would be `https://my-bridge.example.com/webhook/acme`.
See [Adding Endpoints](../using-app-portal/adding-endpoints.mdx) for more on how to do this in the App Portal.


## Using A Polling Endpoint

Bridge can consume messages sent to [Ingest](/ingest/receiving-with-ingest) or any Svix Application with a
[Polling Endpoint](/advanced-endpoints/polling-endpoints) configured as a destination.

This is a great option if you don't want to run a public-internet-facing HTTP server to receive webhooks.
Since Bridge initiates requests from within your environment, you don't need to open any ports in your firewall!

```yaml
receivers:
  - name: "msg-poller-to-rabbitmq-example"
    input:
      type: "svix-message-poller"
      # The consumer id should be unique per the app & sink.
      # This is used to track Bridge's position in the stream so it can resume where it left off
      # after restarting, etc.
      consumer_id: "my-consumer"
      # The app id, and sink id can be found in the URL for the corresponding Polling Endpoint.
      # Eg:
      # https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q
      #                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^        ^^^^^^^^
      app_id: "app_XXXX"
      sink_id: "poll_XXXX"
      # The token can be seen in the UI for the corresponding Polling Endpoint.
      token: "${POLLING_ENDPOINT_TOKEN}"

    transformation: |
      function handler(input) {
        let event_type = input.eventType;
        delete input.eventType;
        // The `payload` field is what will be published to the queue.
        return { payload: { event_type, ...input } };
      }

    output:
      type: "rabbitmq"
      uri: "${QUEUE_URI}"
      exchange: ""
      routing_key: "my_queue"
```

---

Check out the the project on [GitHub][Svix Bridge] for more on how to get started with Bridge.

[Svix Bridge]: https://github.com/svix/svix-webhooks/tree/main/bridge


<!-- Source: https://docs.svix.com/receiving/verifying-payloads/why -->

---
title: Why Verify Webhooks
---
# Why Verify Webhooks

Because of the way webhooks work, attackers can impersonate services by simply sending a fake webhook to an endpoint. Think about it: it's just an HTTP POST from an unknown source. This is a potential security hole for many applications, or at the very least, a source of problems.

<ReceivingSkillCallout />

In order to prevent it, Svix signs every webhook and its metadata with a unique key for each endpoint. This signature can then be used to verify the webhook indeed comes from Svix, and only process it if it is.

Another potential security hole is what's called replay attacks. A [replay attack](https://en.wikipedia.org/wiki/Replay_attack) is when an attacker intercepts a valid payload (including the signature), and re-transmits it to your endpoint. This payload will pass signature validation, and will therefore be acted upon.

To mitigate this attack, Svix includes a timestamp for when the webhook attempt occurred. Our libraries automatically reject webhooks with a timestamp that are more than five minutes away (past or future) from the current time. This requires your server's clock to be synchronised and accurate, and it's recommended that you use [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol) to achieve this.

For additional information about webhook vulnerabilities, please refer to the [webhook security](/security) section of the docs.


<!-- Source: https://docs.svix.com/receiving/webhooks-autoconfig -->

---
title: Receiving with Webhooks AutoConfig
---

# Receiving with Webhooks AutoConfig

Webhooks AutoConfig is an easier way to configure and consume webhooks.

<ReceivingSkillCallout />

With AutoConfig, you can set your webhook endpoint URL, event types, and other configuration in code
and AutoConfig will automatically ensure the settings are up to date. Configuration automatically changes when your
code changes without needing to go to the UI and reconfigure the endpoint.

## How to use Webhooks AutoConfig

<Steps>

### Create an endpoint

Create an endpoint and select AutoConfig as the configuration method.

![AutoConfig option in the Application Portal](/img/autoconfig/autoconfig-create.png)


### Get the AutoConfig token

Get the AutoConfig token.

![AutoConfig token in the Application Portal](/img/autoconfig/autoconfig-token.png)

### Configure your application

Set the endpoint configuration and the AutoConfig token in your application code.

### Call `subscribe()`

Call `subscribe()` to complete the configuration.


<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP"]}>

<TabItem value="JavaScript">
```js
import { AutoConfig } from "svix";

const webhook = new AutoConfig(AUTO_CONFIG_TOKEN, {
  filterTypes: ["invoice.paid", "user.created"],
  url: "https://api.us.example.com/webhooks/acme",
});

await webhook.subscribe();
```
</TabItem>

<TabItem value="Python">
```python
from svix import AutoConfig
from svix.models import EndpointIn

webhook = AutoConfig(
    AUTO_CONFIG_TOKEN,
    EndpointIn(
        url="https://api.us.example.com/webhooks/acme",
        filter_types=["invoice.paid", "user.created"],
    ),
)

webhook.subscribe()
```
</TabItem>

<TabItem value="Rust">
```rust
let webhook = svix::AutoConfig::new(
    AUTO_CONFIG_TOKEN.to_string(),
    svix::EndpointIn {
        url: "https://api.us.example.com/webhooks/acme".to_string(),
        filter_types: Some(vec![
            "invoice.paid".to_string(),
            "user.created".to_string(),
        ]),
        ..Default::default()
    },
)?;

webhook.subscribe().await?;
```
</TabItem>

<TabItem value="Go">
```go
import (
	"context"
	svix "github.com/svix/svix-webhooks/go"
	"github.com/svix/svix-webhooks/go/models"
)

webhook, err := svix.NewAutoConfig(AUTO_CONFIG_TOKEN, models.EndpointIn{
	Url:         "https://api.us.example.com/webhooks/acme",
	FilterTypes: []string{"invoice.paid", "user.created"},
})
if err != nil {
    panic(err)
}

if err := webhook.Subscribe(ctx); err != nil {
    panic(err)
}
```
</TabItem>

<TabItem value="Java">
```java
import com.svix.AutoConfig;
import com.svix.models.EndpointIn;
import java.util.Set;

AutoConfig webhook = new AutoConfig(
        AUTO_CONFIG_TOKEN,
        new EndpointIn()
                .url("https://api.us.example.com/webhooks/acme")
                .filterTypes(Set.of("invoice.paid", "user.created")));

webhook.subscribe();
```
</TabItem>

<TabItem value="Kotlin">
```kotlin
import com.svix.kotlin.AutoConfig
import com.svix.kotlin.models.EndpointIn

val webhook = AutoConfig(
    AUTO_CONFIG_TOKEN,
    EndpointIn(
        url = "https://api.us.example.com/webhooks/acme",
        filterTypes = setOf("invoice.paid", "user.created"),
    ),
)

webhook.subscribe()
```
</TabItem>

<TabItem value="Ruby">
```ruby
require "svix"

endpoint = Svix::EndpointIn.new(
  "url" => "https://api.us.example.com/webhooks/acme",
  "filterTypes" => ["invoice.paid", "user.created"],
)

webhook = Svix::AutoConfig.new(AUTO_CONFIG_TOKEN, endpoint)

webhook.subscribe
```
</TabItem>

<TabItem value="C#">
```csharp
using System;
using Svix;
using Svix.Models;

var webhook = new AutoConfig(
    AUTO_CONFIG_TOKEN,
    new EndpointIn
    {
        Url = "https://api.us.example.com/webhooks/acme",
        FilterTypes = new[] { "invoice.paid", "user.created" },
    });

await webhook.SubscribeAsync();
```
</TabItem>

<TabItem value="PHP">
```php
use Svix\AutoConfig;
use Svix\Models\EndpointIn;

$webhook = new AutoConfig(
    AUTO_CONFIG_TOKEN,
    EndpointIn::create('https://api.us.example.com/webhooks/acme')
        ->withFilterTypes(['invoice.paid', 'user.created']),
);

$webhook->subscribe();
```
</TabItem>
</CodeTabs>

Calling `subscribe()` can be done as part of the application startup process, or in CI/CD as part of the deployment process, so the endpoint configuration is always in sync with the latest version of the application code.

</Steps>


### Payload Verification

When using Webhooks AutoConfig, payload verification is supported out of the box. No need to wire up additional secrets.

To verify the payload, call verify() on the same AutoConfig instance you used to subscribe. The AutoConfig token contains the secret key to verify the payload.

```typescript
import { AutoConfig } from "svix";

const webhook = new AutoConfig(AUTO_CONFIG_TOKEN, {
  filterTypes: ["invoice.paid", "user.created"],
  url: "https://api.us.example.com/webhooks/acme",
});

webhook.verify(payload, headers);
```

`payload` and `headers` depend on the framework (see [Verifying Webhooks](/receiving/verifying-payloads/how)).

<Callout type="important">

**Use the raw request body when verifying webhooks**

You need to use the raw request body when verifying webhooks, as the cryptographic signature is sensitive to even the slightest changes.
You should watch out for frameworks that parse the request as JSON and then stringify it because this can break the signature verification.

See [Verifying Webhooks](/receiving/verifying-payloads/how) for more details.

</Callout>

## Integrating with your application

AutoConfig can be used in a variety of ways, depending on your application and server architecture.

The key is to call `subscribe()` when your endpoint configuration changes, so your code is always in sync with the latest version of the application.
The simplest way to ensure this is to call `subscribe()` in the startup process of your application.

For example, in Express.js, you can call `subscribe()` in an Express.js server:

```js
import express from "express";
import { AutoConfig } from "svix";

const app = express();

const webhook = new AutoConfig(AUTO_CONFIG_TOKEN, {
  filterTypes: ["invoice.paid", "user.created"],
  url: "https://api.us.example.com/webhooks/acme",
});

async function start() {
  await webhook.subscribe();
  app.listen(3000);
}

start();
```

When using a serverless framework, there are lifecycle hooks where you can call `subscribe()` during the server startup process.

For example, in Next.js, you can use [instrumentation](https://nextjs.org/docs/app/guides/instrumentation) to subscribe when a new Next.js server instance is initiated.

```typescript
import { AutoConfig } from "svix";

const webhook = new AutoConfig(AUTO_CONFIG_TOKEN, {
  filterTypes: ["invoice.paid", "user.created"],
  url: "https://api.us.example.com/webhooks/acme",
});

export async function register() {
  await webhook.subscribe();
}
```

Alternatively, AutoConfig can even be used in a CI/CD pipeline, to update the endpoint configuration as part of your deployment process:

```yaml
name: deploy
on:
  push:
    branches: [main]
jobs:
  subscribe-endpoint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci
      - run: |
          node --input-type=module <<'EOF'
          import { AutoConfig } from "svix";

          const webhook = new AutoConfig(AUTO_CONFIG_TOKEN, {
            filterTypes: ["invoice.paid", "user.created"],
            url: "https://api.us.example.com/webhooks/acme",
          });

          await webhook.subscribe();
          EOF
        env:
          AUTO_CONFIG_TOKEN: ${{ secrets.AUTO_CONFIG_TOKEN }}
```


<!-- Source: https://docs.svix.com/retention -->

---
title: Payload Retention
---

# Payload Retention

Svix retains all message payloads (content) for a period of 90 days, after which they are deleted. This ensures that potentially sensitive and private information is not held indefinitely.

## Modifying the retention period

While 90 days is a good default for most use-cases, in some cases, a shorter retention period is preferred. Since different messages may require different retention periods, Svix lets you control the wanted retention on a message by message basis.

To change the retention period just pass the wanted retention period when creating the message by setting the `payload_retention_period` parameter to the wanted number of days.

Here are a few examples for setting the retention to `14` days:

<CodeTabs items={["JavaScript","Python","Go","Rust","Java","Kotlin","Ruby","C#","CLI","PHP","cURL"]}>
<TabItem value="JavaScript">

```js
const svix = new Svix("AUTH_TOKEN");
await svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", {
  eventType: "invoice.paid",
  eventId: "evt_Wqb1k73rXprtTm7Qdlr38G",
  payloadRetentionPeriod: 14,
  payload: {
    id: "invoice_WF7WtCLFFtd8ubcTgboSFNql",
    status: "paid",
    attempt: 2,
  },
});
```

</TabItem>
<TabItem value="Python">

```python
svix = Svix("AUTH_TOKEN")
svix.message.create(
    "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    MessageIn(
        event_type="invoice.paid",
        event_id="evt_Wqb1k73rXprtTm7Qdlr38G",
        payload_retention_period=14,
        payload={
            "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status": "paid",
            "attempt": 2
        }
    )
)
```

</TabItem>
<TabItem value="Go">

```go
svixClient := svix.New("AUTH_TOKEN", nil)
svixClient.Message.Create(ctx, "app_Xzx8bQeOB1D1XEYmAJaRGoj0", &svix.MessageIn{
    EventType:              "invoice.paid",
    EventId:                svix.NullableString("evt_Wqb1k73rXprtTm7Qdlr38G"),
    PayloadRetentionPeriod: 14,
    Payload:                map[string]interface{}{
        "id":      "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        "status":  "paid",
        "attempt": 2,
    },
})
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
svix.message()
    .create(
        "app_Xzx8bQeOB1D1XEYmAJaRGoj0".to_string(),
        MessageIn {
            event_type: "invoice.paid".to_string(),
            event_id: Some("evt_Wqb1k73rXprtTm7Qdlr38G".to_string()),
            payload: json!({
                "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
                "status": "paid",
                "attempt": 2
            }),
            ..MessageIn::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Java">

```java
Svix svix = new Svix("AUTH_TOKEN");
svix.getMessage().create("app_Xzx8bQeOB1D1XEYmAJaRGoj0",
  new MessageIn()
    .eventType("invoice.paid")
    .eventId("evt_Wqb1k73rXprtTm7Qdlr38G")
    .payloadRetentionPeriod(14)
    .payload("{" +
       "\"id\": \"invoice_WF7WtCLFFtd8ubcTgboSFNql\"," +
       "\"status\":  \"paid\"," +
       "\"attempt\": 2" +
      "}"));
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val svix = Svix("AUTH_TOKEN")
svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0",
        MessageIn(
            eventType = "invoice.paid",
            eventId = "evt_Wqb1k73rXprtTm7Qdlr38G")),
            payloadRetentionPeriod = 14,
            payload = mapOf<String, Any>(
                "id" to "invoice_WF7WtCLFFtd8ubcTgboSFNql",
                "status" to "paid",
                "attempt" to 2
            )
```

</TabItem>
<TabItem value="Ruby">

```ruby
svix = Svix::Client.new("AUTH_TOKEN")
svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0",
    Svix::MessageIn.new({
        "event_type" => "invoice.paid",
        "event_id" => "evt_Wqb1k73rXprtTm7Qdlr38G"})),
        "payload" => {
            "id" => "invoice_WF7WtCLFFtd8ubcTgboSFNql",
            "status" => "paid",
            "attempt" => 2
        },
        "payload_retention_period" => 14
    })
)
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
await svix.Message.CreateAsync("app_Xzx8bQeOB1D1XEYmAJaRGoj0", new MessageIn(
    eventType: "invoice.paid",
    eventId: "evt_Wqb1k73rXprtTm7Qdlr38G",
    payloadRetentionPeriod: 14,
    payload: new {
        id: "invoice_WF7WtCLFFtd8ubcTgboSFNql",
        status: "paid",
        attempt: 2,
    },
));
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN="AUTH_TOKEN"
svix message create app_Xzx8bQeOB1D1XEYmAJaRGoj0 '{ "eventType": "invoice.paid", "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G", "payloadRetentionPeriod": 14, "payload": { "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status": "paid", "attempt": 2 } }'
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');


$svix->message->create(
  'app_Xzx8bQeOB1D1XEYmAJaRGoj0',
  MessageIn::create(
    eventType: 'invoice.paid',
    payload: [
      'id' => 'invoice_WF7WtCLFFtd8ubcTgboSFNql',
      'status' => 'paid',
      'attempt' => 2
    ]
  )->withPayloadRetentionPeriod(14)->withEventId('evt_Wqb1k73rXprtTm7Qdlr38G')
);
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X POST "https://api.us.svix.com/api/v1/app/app_Xzx8bQeOB1D1XEYmAJaRGoj0/msg/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer AUTH_TOKEN" \
    -d '{"eventType": "invoice.paid", "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G", "payloadRetentionPeriod": 14, "payload": {"id": "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status": "paid", "attempt": 2}}'
```

</TabItem>
</CodeTabs>

## Delete payloads on successful delivery

As part of the enhanced compliance controls available in the Enterprise tier, Svix supports deleting payloads automatically upon successful delivery or the expiry of the retention period. Whichever comes first.

This is useful for when you want to have the lowest retention required due to compliance reasons; as it ensures that the payload is deleted the moment it's no longer required and no longer than the defined retention period.

While it may be useful in some scenarios, we recommend not using this setting unless you absolutely have to. The reason is that having the payload retained even after successful delivery is often useful for debugging and recovering from errors. While the payload is only deleted on successful delivery, we have seen scenarios where the receiver reported a success, but they actually failed to process the event and wanted to redrive it. If the payload is deleted, they won't be able to do that.

This is a per-environment setting which can be enabled from the [environment settings page](https://dashboard.svix.com/settings) on the dashboard.


<!-- Source: https://docs.svix.com/retries -->

---
title: Retry Schedule
---
# Retry Schedule


Svix attempts to deliver each webhook message based on a retry schedule with exponential backoff.


## The schedule

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

- Immediately
- 5 seconds
- 5 minutes
- 30 minutes
- 2 hours
- 5 hours
- 10 hours
- 10 hours (in addition to the previous)

If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well.

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

Retries will be stopped if the receiving end includes the header `webhook-delivery: abort-message` in its response (see also [Delivery Control](/receiving/delivery-control.mdx)).


## Indicating successful delivery

The way to indicate that a webhook has been processed is by returning a `2xx` (status code `200-299`) response to the webhook message within a reasonable time-frame (15s with Svix). Any other status code, including `3xx` redirects are treated as failures.


## Failed delivery handling

After the conclusion of the above attempts the message will be marked as `Failed` for this endpoint, and the webhook sender's account will get [an operational webhook](./incoming-webhooks.mdx) of type `message.attempt.exhausted` notifying them of this error.


## Disabling failing endpoints

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled and an operational webhook (`EndpointDisabledEvent`) will be sent to your account.
The clock only starts after multiple deliveries failed within a 24 hour span, with at least 12 hours difference between the first and the last failure.

You can disable this behavior from the [Environment settings page](https://dashboard.svix.com/settings/organization/general-settings) on the dashboard.


## Manual retries

Your customers can also use the application portal to manually retry each message at any time, automatically retry ("Recover Failed") all failed messages starting from a given date, or replay messages that have never been attempted to an endpoint ("Replay Missing").

<div style={{ display: 'flex', flexDirection: 'row', gap: '1rem' }}>
  <div>
    ![Recover failed messages dialog](/img/recover-failed.png)
  </div>
  <div>
    ![Replay missing messages dialog](/img/replay-missing.png)
  </div>
</div>

Alternatively, you can use the respective APIs:
- [Resend webhook](https://api.svix.com/docs#operation/resend_webhook_api_v1_app__app_id__msg__msg_id__endpoint__endpoint_id__resend__post) for retrying a single message.
- [Resend failed webhooks](https://api.svix.com/docs#operation/recover_failed_webhooks_api_v1_app__app_id__endpoint__endpoint_id__recover__post) for the failed messages recovery.


<!-- Source: https://docs.svix.com/security -->

---
title: Webhook Security
---
# Webhook Security


Webhooks are a very powerful tool, and when used correctly are also very secure. Svix automatically takes care of these security aspects for you, and offers easy to use library for verifying webhook integrity. For more information, please refer to the [webhook verification section](/receiving/verifying-payloads/why) of the webhook consumption docs.

For more information about the security measures taken by the Svix service, please refer to the [Svix security page](https://www.svix.com/security/).

<Callout type="info">

**Optional reading ahead**

The section below is not required for the normal operation of the Svix service. It's only included here for educational purposes.

</Callout>
## Server-side request forgery (SSRF)

A server-side request forgery (SSRF) attack, is when an attacker abuses functionality on the server to read or update internal resources. In the attack, the attacker supplies or modifies a URL which the server will then make a call to. By carefully selecting the URLs, the attacker may be able to read server configuration such as AWS metadata, connect to internal services like http enabled databases or perform post requests towards internal services which are not intended to be exposed.

Webhooks implementations are especially vulnerable to SSRF as they let their consumers (customers) add any URLs they want, which will be called from the internal webhook system.

For more information about SSRF please refer to the [OWASP entry](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery).

### Preventing SSRF

The main way to protect against SSRF is to prevent the webhooks from calling into internal networks and services. To achieve this you'd want to do two things: the first would be to proxy all webhook requests through a special proxy (like [smokescreen](https://github.com/stripe/smokescreen)) that filters internal IP addresses, and the second would be to put the webhook workers (or proxy) in their own private subnet that can't access internal services.

## Spoofing attacks

Because of the way webhooks work, attackers can impersonate services by simply sending a fake webhook to an endpoint. Think about it: it's just an HTTP POST from an unknown source.


### Preventing spoofing attacks

There are a few ways to prevent or reduce the likelihood of spoofing attacks, though the recommended (and wholly sufficient) way is by signing webhooks.

#### Signature verification

When signing the webhooks it's important to sign not only the payload, but also additional metadata such as idempotency ID and timestamp (more on those later). The signature scheme needs to use strong cryptographic primitives and used correctly. Some implementations use asymmetric signing using Ed25519 or RSA, but it's much more common (and recommended) to use `HMAC-SHA256` which is what Svix uses by default.

For more information, please refer to the [webhook verification](/receiving/verifying-payloads/how-manual) docs.

#### Authentication tokens

Like normal HTTP requests, webhooks can authenticate using a pre-shared authentication token, HTTP Basic Auth, or any other common HTTP authentication method. This is not recommended for a variety of reasons, the first one is the danger of giving the webhook provider a token with more access than needed (as in, a token that can also make API calls) which is a common pitfall, and the other is that because of how webhooks work, the server can potentially be tricked to send the request to the wrong destination, exposing the token.


#### IP allow list

An IP allow list is an insecure mechanism when used on its own, as it's not meant for authentication. Svix supports sending from a specific set of source IPs. The reason why Svix supports it, is so that webhook consumers that have firewalls can add Svix to the allow list to ensure delivery.

Relying on it however is insufficient, because depending on the cloud provider you use, you may be sharing IPs with other machines. Even if you have your own private IPs, you may accidentally release an IP address back to the cloud provider which can then be used to send malicious requests, and last but not least, this means that one customer of the service can trigger webhooks affecting another customer (because the sender will be from the same set of IP addresses) making the security insufficient.

## Replay attacks

A replay attack is an attack when a valid data transmission is duplicated maliciously or fraudulently.

A bad actor can intercept (and potentially modify) a request before it reaches its destination, then replay it. Even if the payload is encrypted or signed and can't be edited, simply repeating a request can cause a lot of problems (e.g. duplicating a purchase event).

### Preventing replay attacks

#### Timestamps in the signature

One way to limit the risks of replay attacks is by adding a timestamp to each webhook attempt and having the consumers verify it and ensuring it falls within a specific allowed tolerance. This method requires that the consumer has the correct time set on their machine (usually using NTP), and that the timestamp is also signed by the signature mentioned above (otherwise it can be spoofed).

#### Idempotency

With respect to APIs, idempotence means that you would get the same result whether you make an identical API call once or many times. If your endpoints are idempotent, any webhook requests will only be processed once, even if they are received multiple times. This can be done either implicitly (e.g. the content of the webhook is such that processing it multiple times doesn't make sense) or explicitly, which means adding a special ID for each message which the consumer can validate against.


## Man-in-the-middle attack

Man-in-the-middle (MITM) attack is a form of eavesdropping in which the attacker secretly relays and possibly alters the communications between two parties who believe they are directly communicating with each other.

### Preventing man-in-the-middle attacks

The most common way to avoid a MITM attack is to always use HTTPS URLs to ensure that the request is encrypted and the connection is verified.


## What about mTLS?

By default the TLS protocol only proves the identity of the server to the client, and the authentication of the client to the server is left to the application layer. TLS also offers client-to-server authentication using client-side certificates.

While it solves most of the above issues, it's rarely used as it puts a massive burden on webhook consumers. The problem is that it requires provisioning of client certifications for usage with the webhook receiver, and requires the consumer to know how to handle mTLS which is not possible in most managed cloud environments.

In addition, unless a specific certificate is created for each endpoint, it suffers from the same issue that the "IP allow list" solution suffers from above: different customers of the same webhook service can maliciously trigger authenticated webhooks to one another.


<!-- Source: https://docs.svix.com/sending-messages-with-bridge -->

---
title: Sending Messages with Bridge
---
# Sending Messages with Bridge


If you have messages moving through queues that you'd like to send as webhooks, [Svix Bridge] can help.

Bridge is an agent that can read from a queue, transform the message with a JavaScript function, then forward to Svix for delivery.
With a small amount of configuration, you can start consuming events, reshaping, and sending webhooks in minutes.

For example, reading from RabbitMQ, modifying the payload in JS, then sending to Svix might look like this:

```yaml
senders:
  - name: 'send-from-rabbitmq-example'
    input:
      type: 'rabbitmq'
      uri: '${RABBITMQ_URI}'
      queue_name: '${QUEUE_NAME}'

    transformation: |
      function handler(input) {
        return {
          appId: input.key,
          message: {
            eventType: input.event_type,
            payload: input.data
          }
        };
      }

    output:
      type: 'svix'
      token: '${SVIX_TOKEN}'
```

In this example, we're subscribing to messages from a queue, making the payload conform to the expected shape,
including the required fields:

- `appId`
- `message.eventType`
- `message.payload`


Check out the the project on [GitHub][Svix Bridge] for more on how to get started with Bridge.

[Svix Bridge]: https://github.com/svix/svix-webhooks/tree/main/bridge


<!-- Source: https://docs.svix.com/stream/event-types/introduction -->

---
title: "Event Types"
---
# Event Types

Just like Svix Webhooks, each event sent through Svix Stream has an associated event type. Event types are identifiers denoting the type of event being sent, and are primarily used by Sinks to filter on events.

Event types are just a string, for example: `user.signup`, `invoice.paid` and `workflow.completed`.

You can see all of your environment's Stream Event Types under the "Event Types" tab in the Stream Dashboard.

![stream-recent-events](/img/stream/event-types/list.png)

You can create event types in the Stream Dashboard, or via the [API](https://api.svix.com/docs#tag/Stream-Event%20Type/operation/v1.stream.event-type.create).

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const streamEventTypeOut = await svix.streaming.eventType.create({
    name: "user.signup",
    description: null,
    featureFlags: ["cool-new-feature"]
});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, StreamEventTypeIn

stream_event_type_out = svix.streaming.event_type.create(StreamEventTypeIn(
    name="user.signup",
    description=None,
    feature_flags=["cool-new-feature"]
))
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let stream_event_type_out = svix
    .streaming()
    .event_type()
    .create(StreamEventTypeIn {
        name: "user.signup".to_string(),
        description: None,
        feature_flags: Some(vec!["cool-new-feature".to_string()]),
    }, None)
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
streamEventTypeOut, err := svixClient.Streaming.EventType.Create(ctx, &StreamEventTypeIn{
    Name: "user.signup",
    Description: nil,
    FeatureFlags: []string{"cool-new-feature"},
})
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.Svix;
import com.svix.models.StreamEventTypeIn;


StreamEventTypeOut streamEventTypeOut = svix.getStreaming().getEventType().create(new StreamEventTypeIn()
    .name("user.signup")
    .description(null)
    .featureFlags(new String[]{"cool-new-feature"})
);
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Svix;
import com.svix.kotlin.models.StreamEventTypeIn;

val svix = Svix("AUTH_TOKEN");
val streamEventTypeOut = svix.streaming.eventType.create(StreamEventTypeIn()
    .name("user.signup")
    .description(null)
    .featureFlags(arrayOf("cool-new-feature"))
)
```

</TabItem>
<TabItem value="Ruby">

```ruby
stream_event_type_out = svix.streaming.event_type.create(Svix::StreamEventTypeIn.new({
    "name": "user.signup",
    "description": nil,
    "feature_flags": ["cool-new-feature"]
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
var streamEventTypeOut = await svix.Streaming.EventType.CreateAsync(new StreamEventTypeIn{
    name: "user.signup",
    description: null,
    featureFlags: new string[] {"cool-new-feature"}
});
```

</TabItem>
<TabItem value="CLI">

```shell
Support for svix-cli coming soon
```

</TabItem>
<TabItem value="cURL">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'

curl -X 'POST' \
  'https://api.us.svix.com/api/v1/stream/event-type' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "user.signup",
        "description": null,
        "featureFlags": ["cool-new-feature"]
    }'
```

</TabItem>
</CodeTabs>

## Event Type Filtering

When creating a [Sink](../sinks/introduction), you can optionally specify which event types the Sink should filter on.

In this example, the Google Cloud Storage sink will only receive events with the event type `user.created` or `user.login`.

![stream-recent-events](/img/stream/sink-event-type-filtering.png)

If no event types are selected when creating a Sink, the Sink will receive all events, regardless of the event type.


<!-- Source: https://docs.svix.com/stream/introduction -->

---
title: "Introduction"
---
# Introduction

Svix Stream is an event streaming platform that enables services to reliably deliver events to multiple destinations through a single integrated API.

The core of Svix Stream is built on top of **Streams**, **Events**, and **Sinks**. Events are pushed to a Stream, and Svix will batch, transform, and dispatch the events to one or more Sinks.

![stream-diagram](/img/stream/introduction/diagram.png)

## Streams

**Streams** are unbounded, append only data stores, where events are stored and processed in a stable, first-in-first-out ordering.

Creating a Stream is simple using the [API](https://api.svix.com/docs#tag/Stream/operation/v1.stream.stream.create):

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const streamOut = await svix.streaming.stream.create({
    name: "My Stream",
    uid: "unique-identifier"
});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, StreamIn

stream_out = svix.streaming.stream.create(StreamIn(
    name="My Stream",
    uid="unique-identifier"
))
```

</TabItem>
<TabItem value="Rust">

```rust
let svix = Svix::new("AUTH_TOKEN".to_string(), None);

let stream_out = svix
    .streaming()
    .stream()
    .create(
        StreamIn {
            name: "My Stream".to_string(),
            uid: Some("unique-identifier".to_string()),
        },
        None
    ).await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
streamOut, err := svixClient.Streaming.Stream.Create(ctx, &svix.StreamIn{
    Name: "My Stream",
    Uid: "unique-identifier",
})
```

</TabItem>
<TabItem value="Java">

```java
StreamOut streamOut = svix.getStreaming().getStream().create(new StreamIn()
    .name("My Stream")
    .uid("unique-identifier")
);
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.Svix;
import com.svix.kotlin.models.StreamIn;

val streamOut = svix.streaming.stream.create(StreamIn()
    .name("My Stream")
    .uid("unique-identifier")
)
```

</TabItem>
<TabItem value="Ruby">

```ruby
stream_out = svix.streaming.stream.create(Svix::StreamIn.new({
    "name": "My Stream",
    "uid": "unique-identifier"
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.svix.com"));

var streamOut = await svix.Streaming.Stream.CreateAsync(new StreamIn{
    name: "My Stream",
    uid: "unique-identifier"
});
```

</TabItem>
<TabItem value="CLI">

```shell
Support for svix-cli coming soon
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "My Stream",
        "uid": "unique-identifier"
    }'
```

</TabItem>
</CodeTabs>


The new Stream will look something like:

```json
{
    "id": "strm_31BLjHyfpwFzMmLjO0MrL",
    "uid": "unique-identifier",
    "name": "My Stream",
    "createdAt": "2025-09-29T19:41:36.153Z",
    "updatedAt": "2025-09-29T19:41:36.153Z",
    "metadata": {}
}
```

And can be viewed in the Stream section of the Svix Dashboard.

![stream-diagram](/img/stream/introduction/list-streams.png)

## Events

With the new Stream, you can immediately start writing events.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
const events = await svix.streaming.events.create("stream_id", {
    events: [
        {
            "eventType": "user.created",
            "payload": "{ \"email\": \"bob@enterprise.io\" }"
        },
        {
            "eventType": "user.login",
            "payload": "{ \"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\" }"
        }
    ]
});
```

</TabItem>
<TabItem value="Python">

```python
create_stream_events_out = svix.streaming.events.create("stream_id", CreateStreamEventsIn(
    events=[
        {
            "eventType": "user.created",
            "payload": '{"email": "bob@enterprise.io"}'
        },
        {
            "eventType": "user.login",
            "payload": '{"id": 12, "timestamp": "2025-07-21T14:23:17.861Z"}'
        }
    ]
))
```

</TabItem>
<TabItem value="Rust">

```rust
let create_stream_events_out = svix.streaming().events().create("stream_id", CreateStreamEventsIn {
    events: vec![
        json!({
            "eventType": "user.created",
            "payload": "{\"email\": \"bob@enterprise.io\"}"
        }),
        json!({
            "eventType": "user.login",
            "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
        })
    ],
    stream: None,
}, None).await?;
```

</TabItem>
<TabItem value="Go">

```go
createStreamEventsOut, err := svixClient.Streaming.Events.Create(ctx, "stream_id", &CreateStreamEventsIn{
    Events: []interface{}{
        map[string]interface{}{
            "eventType": "user.created",
            "payload":   `{"email": "bob@enterprise.io"}`,
        },
        map[string]interface{}{
            "eventType": "user.login",
            "payload":   `{"id": 12, "timestamp": "2025-07-21T14:23:17.861Z"}`,
        },
    },
})
```

</TabItem>
<TabItem value="Java">

```java
CreateStreamEventsOut createStreamEventsOut = svix.getStreaming().getEvents().create("stream_id", new CreateStreamEventsIn()
    .events(new Object[]{
        Map.of(
            "eventType", "user.created",
            "payload", "{\"email\": \"bob@enterprise.io\"}"
        ),
        Map.of(
            "eventType", "user.login",
            "payload", "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
        )
    })
);
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
val createStreamEventsOut = svix.streaming.events.create("stream_id", CreateStreamEventsIn()
    .events(arrayOf(
        mapOf(
            "eventType" to "user.created",
            "payload" to "{\"email\": \"bob@enterprise.io\"}"
        ),
        mapOf(
            "eventType" to "user.login",
            "payload" to "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
        )
    ))
)
```

</TabItem>
<TabItem value="Ruby">

```ruby
create_stream_events_out = svix.streaming.events.create("stream_id", Svix::CreateStreamEventsIn.new({
    "events": [
        {
            "eventType" => "user.created",
            "payload" => '{"email": "bob@enterprise.io"}'
        },
        {
            "eventType" => "user.login",
            "payload" => '{"id": 12, "timestamp": "2025-07-21T14:23:17.861Z"}'
        }
    ]
}))
```

</TabItem>
<TabItem value="C#">

```csharp
var createStreamEventsOut = await svix.Streaming.Events.CreateAsync("stream_id", new CreateStreamEventsIn{
    events: new Object[] {
        new {
            eventType = "user.created",
            payload = "{\"email\": \"bob@enterprise.io\"}"
        },
        new {
            eventType = "user.login",
            payload = "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
        }
    }
});
```

</TabItem>
<TabItem value="CLI">

```shell
Support for svix-cli coming soon
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"bob@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

</TabItem>
</CodeTabs>


**Events** written to a Stream always contain two fields:
* `eventType` - An identifier denoting the type of event being sent. (For more info, see [Event Types](./event-types/introduction))
* `payload` - A string representing the event. Payloads will typically be JSON, though in practice they can be any format that fits your use case.

In the Stream Dashboard, you'll see the most recent events that have been sent to the Stream.

![stream-recent-events](/img/stream/introduction/stream-recent-events.png)

Events are persisted to the Stream for 14 days. While the Events are saved to the Stream, they'll be dispatched, in order, to one or more **Sinks** attached to the Stream.

## Sinks

Sinks define where Events in the Stream are sent, and can be anything from an [HTTP endpoint](./sinks/http) to an Object Storage bucket ([S3](./sinks/s3), [Google Cloud Storage](./sinks/gcs), [Azure Blob Storage](./sinks/azure_blob)), or even an [Open Telemetry Trace collector](./sinks/otel_trace).

When configuring Sinks, you control:

* Which event types the Sink is subscribed to.
* How events are batched together before dispatch.
* Custom JavaScript transformations to modify events before delivery.

For more information on configuring Sinks, see [Introduction to Sinks](./sinks/introduction)


<!-- Source: https://docs.svix.com/stream/portal -->

---
title: Stream Portal
---
# Stream Portal

Svix comes with a Stream Portal for your users (sink consumers) that you can use out of the box. Your users can then use it to configure sinks, debug delivery, as well as inspect and retry events. This is the easiest way to get started, but you can alternatively use the API to build your own.

You can preview the Stream portal by clicking the "Preview Stream Portal" in the dashboard.

![App Portal screenshot](/img/stream/preview-stream-portal.png)

On the Stream Portal, you can view and configure all of the Sinks for your stream.

![App Portal screenshot](/img/stream/stream-portal.png)

In addition, you can see the most recent 50 events sent to the stream.

![App Portal screenshot](/img/stream/list-events.png)


<!-- Source: https://docs.svix.com/stream/sinks/azure_blob -->

---
title: Azure Blob Storage
---
# Azure Blob Storage

Events can be sent to an Azure Blob Storage container using the `azureBlobStorage` sink type.

Like all Sinks, Azure Blob Storage containers can be created in the Stream Portal...

![azure-recent-events](/img/stream/azure-blob-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "azureBlobStorage",
  "config": {
    "container": "my-azure-blob-storage-container",
    "account": "my-account",
    "accessKey": "*******"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event batch written to your container will put a new blob in the container.

# Transformations

By default, all `azureBlobStorage` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing what will be put to the bucket.
 * @returns returns.config
 * @returns returns.config.format - The format of the request object put to the bucket. Valid values are "jsonl", "json", or "raw" (Defaults to jsonl).
 * @returns returns.config.key - The name of the object that will be put to the bucket. This will be suffixed with a timestamp to avoid duplicate object names.
 * @returns returns.data - The array of events to send to the bucket. This will be formatted according to the format.
 */
function handler(input) {
    return {
        config: {
            format: "jsonl",
            key: "object-generated-by-svix"
        },
        data: input.events
    }
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.stream.events.create).

`config` describes the blob put in the container - the key name of the blob, and the format of the blob saved to the container.

By default, the actual blob key is always suffixed with a timestamp after the transformations are run. This ensures each event batch is saved as a unique item in the container.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would result in following blob being uploaded to your container.

```jsonl
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

If you want to control the format of the object more precisely, you can use `config.format = "raw"`, and set `data` to a string of the exact file contents you want.


<!-- Source: https://docs.svix.com/stream/sinks/bigquery -->

---
title: Google BigQuery
---
# Google BigQuery

Events can be sent to a Google BigQuery table using the `bigQuery` sink type.

Like all Sinks, BigQuery sinks can be created in the Stream Portal...

![big-query](/img/stream/bigquery-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "bigQuery",
  "config": {
    "projectId": "my-gcp-project",
    "datasetId": "my_dataset",
    "tableId": "events",
    "credentials": "<json encoded service account credentials>"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event batch is inserted into the configured BigQuery table.

- `projectId` — the GCP project that owns the dataset.
- `datasetId` — the BigQuery dataset that contains the table.
- `tableId` — the table that receives the rows.
- `credentials` — a Google Cloud service account credentials JSON object, provided as a string.

## Destination table

Without a transformation, Svix inserts each event into the table identified by `projectId`, `datasetId`, and `tableId` using two columns: `id` and `payload`. Svix generates a unique `id` for each row and writes the raw event payload to `payload`.

The table must already exist before you enable the sink. For the default behavior, create it with:

```sql
CREATE TABLE `my-gcp-project.my_dataset.events` (
  id STRING,
  payload STRING
);
```

If you use a transformation (below), you control the columns each row contains, so your table can use any schema you like — as long as it matches the rows your transformation returns.

# Transformations

Each event is inserted into BigQuery as a row. A transformation returns the `rows` to insert, where each row is an object whose keys match your table's columns.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the rows to insert.
 * @returns returns.rows - The array of rows to insert. Each row is an object whose keys match the columns of your BigQuery table.
 */
function handler(input) {
    const rows = input.events.map((event) => ({
        id: crypto.randomUUID(),
        payload: JSON.stringify(event.payload)
    }));

    return { rows };
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

Each entry in the returned `rows` array is inserted as a separate row. The object keys must match the column names of your table. To write different columns, adjust the objects in `rows` and your table schema to match.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The transformation above inserts two rows into your table.

| `id` | `payload` |
| --- | --- |
| `1f0a8c1e-...` | `{"email":"joe@enterprise.io"}` |
| `4b9d2e7a-...` | `{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"}` |


<!-- Source: https://docs.svix.com/stream/sinks/clickhouse -->

---
title: ClickHouse
---
# ClickHouse

Events can be sent to a ClickHouse table using the `clickhouse` sink type.

Like all Sinks, ClickHouse sinks can be created in the Stream Portal...

![Clickhouse-Create](/img/stream/clickhouse-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "clickhouse",
  "config": {
    "url": "https://my-clickhouse.example.com:8443",
    "username": "default",
    "password": "*******",
    "database": "default",
    "tableName": "events"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event batch is inserted into the configured ClickHouse table.

- `url` — the HTTP URL of your ClickHouse server (e.g. `https://my-clickhouse.example.com:8443`).
- `username`, `password` — the credentials used to authenticate.
- `tableName` — the table that receives the rows.
- `database` — the database that contains the table. Defaults to `default`.

## Destination table

Without a transformation, Svix inserts each event's payload directly into the table using ClickHouse's [`JSONEachRow`](https://clickhouse.com/docs/interfaces/formats/JSONEachRow) format. The top-level fields of each payload must match the columns of your table.

The table must already exist before you enable the sink. For example, for payloads shaped like `{"email": "...", "username": "..."}`, create the table with:

```sql
CREATE TABLE events (
  email String,
  username String
)
ENGINE = MergeTree()
ORDER BY tuple();
```

Unlike some other warehouse Sinks, ClickHouse does not add any columns of its own — you define the full schema, and the payload fields are matched to it by name.

# Transformations

If your payloads don't already match your table's columns, add a transformation that returns the `rows` to insert. Each row is an object whose keys match your table's columns.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the rows to insert.
 * @returns returns.rows - The array of rows to insert. Each row is an object whose keys match the columns of your ClickHouse table.
 */
function handler(input) {
    const rows = input.events.map((event) => ({
        email: event.payload.address,
        username: event.payload.handle
    }));

    return { rows };
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

Each entry in the returned `rows` array is inserted as a separate row using `JSONEachRow`, so the object keys must match the column names of your table.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"address\": \"joe@enterprise.io\", \"handle\": \"joe\"}"
            },
            {
                "eventType": "user.created",
                "payload": "{\"address\": \"amy@enterprise.io\", \"handle\": \"amy\"}"
            }
        ]
    }'
```

The transformation above inserts two rows into your table, mapping each payload's `address` and `handle` fields onto the `email` and `username` columns.

| `email` | `username` |
| --- | --- |
| `joe@enterprise.io` | `joe` |
| `amy@enterprise.io` | `amy` |


<!-- Source: https://docs.svix.com/stream/sinks/eventbridge -->

---
title: Amazon EventBridge
---
# Amazon EventBridge

Events can be sent to Amazon EventBridge using the `eventBridge` sink type.

Like all Sinks, EventBridge sinks can be created in the Stream Portal...

![eventbridge-create](/img/stream/eventbridge-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "eventBridge",
  "config": {
    "eventBusName": "my-event-bus",
    "detailType": "application/json",
    "region": "us-east-1",
    "accessKeyId": "AKIA3LIKMTLDNWBX2PPD",
    "secretAccessKey": "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"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event in the batch is sent to EventBridge as a separate entry.

- `eventBusName` — the name or ARN of the event bus that receives the events.
- `detailType` — a free-form string (max 128 characters) used as the `detail-type` of each event. Defaults to `application/json`.
- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.

Each event is published with its `source` set to `svix-webhooks-<stream_id>`, its `detail-type` set to the configured `detailType`, and its `detail` set to the message produced by the transformation. You can match on the `source` and `detail-type` when writing EventBridge rules.

# Transformations

By default, all `eventBridge` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object containing the request body
 * @returns returns.payloads - The array of messages (strings) to send to the Sink. Each payload is a distinct message sent to the Sink.
 */
function handler(input) {

  const payloads = input.events.map((event) => JSON.stringify(event))

  return {
    payloads
  }
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

Each entry in the returned `payloads` array becomes the `detail` of a separate EventBridge event. By default, each event is serialized to a JSON string containing its `payload` and `eventType`.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would send two events to your event bus, with the following `detail` bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the `detail` of each event, return your own array of strings in `payloads`. Each string becomes the `detail` of one EventBridge event.

EventBridge accepts at most 10 entries per request, so larger batches are automatically split across multiple `PutEvents` calls.


<!-- Source: https://docs.svix.com/stream/sinks/gcs -->

---
title: Google Cloud Storage
---
# Google Cloud Storage

Events can be sent to a Google Cloud Storage bucket using the `googleCloudStorage` sink type.

Like all Sinks, GCS buckets can be created in the Stream Portal...

![gcs-recent-events](/img/stream/gcs-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "googleCloudStorage",
  "config": {
    "bucket": "my-bucket-name",
    "credentials": "<json encoded service account credentials>"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event batch written to your GCS bucket will put a new object in the bucket.

# Transformations

By default, all `googleCloudStorage` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing what will be put to the bucket.
 * @returns returns.config
 * @returns returns.config.format - The format of the request object put to the bucket. Valid values are "jsonl", "json", or "raw" (Defaults to jsonl).
 * @returns returns.config.key - The name of the object that will be put to the bucket. This will be suffixed with a timestamp to avoid duplicate object names.
 * @returns returns.data - The array of events to send to the bucket. This will be formatted according to the format.
 */
function handler(input) {
    return {
        config: {
            format: "jsonl",
            key: "object-generated-by-svix"
        },
        data: input.events
    }
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.stream.events.create).

`config` describes the object put in the sink - the key name of the object, and the format of the object saved to the bucket.

By default, the actual object key is always suffixed with a timestamp after the transformations are run. This ensures each event batch is saved as a unique object in the bucket.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would result in the following object being uploaded to your bucket.

![gcs-recent-events](/img/stream/gcs-example.png)

And the files contents would match the jsonl format.

```jsonl
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

If you want to control the format of the object more precisely, you can use `config.format = "raw"`, and set `data` to a string of the exact file contents you want.


<!-- Source: https://docs.svix.com/stream/sinks/http -->

---
title: HTTP
---
# HTTP Endpoints

Events can be sent to any arbitrary HTTP endpoint using the `http` sink type.

Like all Sinks, HTTP receivers can be created in the Stream Portal...

![stream-recent-events](/img/stream/http-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "http",
  "config": {
    "url": "https://example.com"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 100,
  "maxWaitSecs": 0,
  "eventTypes": [],
  "metadata": {}
}'
```

Just like with Svix Endpoints, you can [configure](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink-headers-patch) the `http` sink with custom headers that will be injected on each request.

![stream-recent-events](/img/stream/http-headers.png)


# Transformations

By default, all `http` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.url - The http(s) url of the Sink (string).
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The event payload (string or JSON).
 * @param input.events[].eventType - The event type (string).
 *
 * @returns Object describing the HTTP request.
 * @returns returns.config - An object describing the configuration of the request.
 * @returns returns.config.format - The format of the request body. Valid values are "json" or "raw".
 * @returns returns.config.headers - An object describing the headers of the request. All keys and values must be strings. Optional.
 * @returns returns.config.method - The HTTP method of the request. Valid values are "POST", "PUT", and "PATCH". If left unspecified, the request defaults to "POST".
 * @returns returns.config.url - The url of the request. Optional. If left unspecified, the request defaults to the original sink's url.
 * @returns returns.data - The array of events to send in the HTTP request. If config.format is "json", the data will be sent as a JSON object. If config.format is "raw", data
 *                         should be a string and will be sent as the request body.
 * @returns returns.cancel - An optional bool indicating whether the request should be cancelled. If true, the request will not be sent.
 */
function handler(input) {
  return {
    config: {
        format: "json",
        headers: {},
        method: "POST",
        url: input.url
    },
    data: input.events,
    cancel: false
  }
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.stream.events.create).

`config` describes the request - the sink URL, the http verb, the desired format of the request (e.g. `json`), and any additional headers you want to inject in the request.

By default, `config` can be omitted, in which case a `POST` request with `json` format will be sent.

`data` is what will be sent in the request body. By default, we send the `input.events` without any modifications.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would result in the following, semantically equivalent, request being made to the Sink:

```shell
curl -X 'POST' \
  'https://the-sink-url' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Svix-Stream/1.70.0' \
  -H 'Svix-Id: qoMDqncM7278tPF06iwYlVgkeugYg8UdwKScB8kpCdQ=-1' \
  -H 'Svix-Timestamp: 1755100641' \
  -d '{
        "data": [
            {
                "eventType": "user.created",
                "payload": {"email": "joe@enterprise.io"}"
            },
            {
                "eventType": "user.login",
                "payload": {"id": 12, "timestamp": "2025-07-21T14:23:17.861Z"}
            }
        ]
    }'
```

(Note that the same headers Svix includes with webhooks, are also included when dispatching to a Stream's sinks)

If you want tighter control over the request body, you can use set `config.format = "raw"`. This will set the body to the `data` field without any modifications.

For example, the following transformation code would make a `PATCH` request with a json lines payload.

```JavaScript
function handler(input) {

  // note that the body here is just a string.
  const body = input
    .events
    .map((event) => JSON.stringify(event.payload))
    .join("\n");

  return {
    config: {
        format: "raw",
        method: "PATCH"
    },
    data: body,
  }
}
```

And would be semantically equivalent to the following curl request

```shell
curl -X 'PATCH' \
  'https://the-sink-url' \
  -H 'User-Agent: Svix-Stream/1.70.0' \
  -H 'Svix-Id: qoMDqncM7278tPF06iwYlVgkeugYg8UdwKScB8kpCdQ=-1' \
  -H 'Svix-Timestamp: 1755100641' \
  -d '{"email": "joe@enterprise.io"}
      {"id": 12, "timestamp": "2025-07-21T14:23:17.861Z"}'
```


<!-- Source: https://docs.svix.com/stream/sinks/introduction -->

---
title: Introduction
---
# Introduction to Sinks

Sinks define where events are sent, and how events are shaped before dispatch.

The following sink types are supported by Svix Stream:

* [HTTP Endpoints](./http)
* [OpenTelemetry Trace Collector](./otel_trace)
* [Amazon S3](./s3)
* [Google Cloud Storage](./gcs)
* [Azure Blob Storage](./azure_blob)
* [Snowflake](./snowflake)
* [RabbitMQ](./rabbitmq)
* [Amazon EventBridge](./eventbridge)
* [Amazon SNS](./sns)
* [Amazon SQS](./sqs)
* [Google BigQuery](./bigquery)
* [ClickHouse](./clickhouse)
* [Amazon Redshift](./redshift)
* [Polling Endpoint](./poller)

All Sinks can be configured with event type filtering, batching, and transformations, and can be created through the Stream Portal or the [API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

## Event Type Filtering

When creating a Sink, you can optionally specify which event types the sink should filter on.

In this example, the Google Cloud Storage sink will only receive events with the event type `user.created` or `user.login`.

![stream-recent-events](/img/stream/sink-event-type-filtering.png)

If no event types are selected when creating a Sink, the sink will receive all events, regardless of the event type.

## Batching

All Sinks (with the exception of Polling Endpoints) can be configured with a `batchSize` and `maxWaitSecs`, which determines how large and how frequently batches are sent.

![stream-recent-events](/img/stream/batching.png)

Events are dispatched when either condition is met:

* Even events have accumulated to meet the batch size, _or_
* The `maxWaitSecs` has passed since the last event was dispatched

To maximize throughput on the Sink, keep batch sizes large and set `maxWaitSecs` to `0`.

To minimize resource utilization on the Sink, keep batch sizes large and set `maxWaitSecs` to the largest value your Sink can tolerate.

## Transformations

All Sinks (with the exception of Polling Endpoints) are configured with custom transformation code, which gives precise control over how events are shaped before being sent to the sink.

![transformation](/img/stream/transformation_generic.png)

Because transformations shape the request to the Sink, each sink type has its own transformation template. `http` Sinks let you configure the parameters like URL, body, and headers, while object storage Sinks (`amazonS3`, `googleCloudStorage`) let you control the object key name and contents.

For example, the transformation code for `http` Sinks can be as simple as:

```JavaScript
/**
 * @param input.events - The array of events in the batch.
 * @param input.events[].payload - The event payload (string or JSON).
 * @param input.events[].eventType - The event type (string).
 */
function handler(input) {
  return {
    config: {
        format: "json",
    },
    data: input.events
  }
}
```

This would take all the events in the batch, and make a `POST` request to the HTTP endpoint with the body:
```json
{
    "data": [
        {
            "eventType": "user.created",
            "payload": { "email": "joe@enterprise.io" }
        },
        {
            "eventType": "user.login",
            "payload": {"id": 12, "timestamp": "2025-07-21T14:23:17.861Z"}
        }
    ]
}
```

You can also test your transformation code on custom events directly in the Stream Portal in the transformations tab.

![transformation-test](/img/stream/test-transformation.png)

## Dispatch Order

Events are always dispatched to Sinks in the same order that Events were persisted to the Stream.

Consider events written to the Stream as such:

```shell
curl -X POST 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/events' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer ************' \
    -D '{
        "events": [
            {
                "payload": "first event",
                "eventType": "event.one"
            },
            {
                "payload": "second event",
                "eventType": "event.two"
            },
            {
                "payload": "third event",
                "eventType": "event.three"
            },
            {
                "payload": "fourth event",
                "eventType": "event.four"
            },
            {
                "payload": "fifth event",
                "eventType": "event.five"
            }
        ]
}'
```

These events will be persisted to the Stream in the same order they were written.

![stream-recent-events](/img/stream/five-events.png)

When dispatch occurs, the order in the Stream is preserved. `event.one` will always be sent before (or batched in the same request as) `event.two`, `event.two` will always be sent before (or batched in the same request as) `event.three`, and so on.

## Dispatch Failures and Retries

If dispatch fails, Svix Stream will make a best effort to deliver the events by retrying with exponential backoff.

You can see if dispatch is in a `retrying` state on the sink's page in the Stream Portal.

![stream-recent-events](/img/stream/retrying-status.png)

The status bar will also tell you:
1. When the next retry is scheduled at.
2. What the reason for the dispatch failure was.

If dispatch fails because the sink is misconfigured, or the retry schedule was exhausted, the sink will automatically be disabled.

![stream-recent-events](/img/stream/failed-status.png)

While a sink is disabled, events can still be written to the Stream without interruption.

In the UI, you can still alter the sink's configuration, and re-enable the sink once you're sure the error is resolved. Once a sink is re-enabled, it will resume dispatching events from where it left off.


<!-- Source: https://docs.svix.com/stream/sinks/otel_trace -->

---
title: OpenTelemetry Tracing
---
import OpenTelemetryProviderNotes from '../../_common/otel-provider-notes.mdx'

# OpenTelemetry Tracing

Events can be sent to an OpenTelemetry tracing collector using the `otelTracing` sink type.

Like all Sinks, OpenTelemetry tracing collectors can be created in the Stream Portal...

![otel-recent-events](/img/stream/otel-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "otelTracing",
  "config": {
    "url": "https://otlp-gateway-prod-us-east-2.grafana.net/otlp/v1/traces"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 100,
  "maxWaitSecs": 0,
  "eventTypes": [],
  "metadata": {}
}'
```

Typically, the `url` of an OpenTelemetry tracing sink will be the `OTEL_EXPORTER_OTLP_ENDPOINT` URL given by your opentelemetry provider, appended with `/v1/traces`, following the [conventions of OTLP exporters](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint).

Just like with `http` Sinks, you can [configure](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink-headers-patch) the `otelTracing` sink with custom headers that will be injected on each request.

![stream-recent-events](/img/stream/otel-headers.png)


# Transformations

By default, all `otelTransformation` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the otel spans to be created.
 * @returns returns.config
 * @returns returns.config.serviceName - The name of the otel service.
 * @returns returns.config.scope - The scope of the otel service. Includes a name and version string.
 * @returns returns.spans - Array of objects, each describing an otel span.
 * @returns returns.spans[].kind - The kind of span. Can be one of "SERVER", "CLIENT", "PRODUCER", "CONSUMER", or "INTERNAL". (Defaults to "INTERNAL")
 * @returns returns.spans[].traceIdKey - An optional string. Attaches the span to traces with the same traceIdKey.
 * @returns returns.spans[].spanIdKey - An optional string. Identifies the span.
 * @returns returns.spans[].parentSpanIdKey - An optional string. Attaches the span to a parent with the same spanIdKey.
 * @returns returns.spans[].startTime - The start time of the span. Must be a string in ISO 8601 format.
 * @returns returns.spans[].endTime - The end time of the span. Must be a string in ISO 8601 format.
 * @returns returns.spans[].name - The name of the span.
 * @returns returns.spans[].attributes - An optional object. Contains key-value pairs of attributes.
 */
function handler(input) {
    const spans = input.events.map((event) => {
        return {
            // The start and end times of the span.
            // You'll likely want to override these based on values from the event.payload.
            startTime: new Date().toISOString(),
            endTime: new Date().toISOString(),

            name: event.eventType,
            attributes: event.payload
        }
    })

    return {
        config: {
            serviceName: "svix.stream",
            scope: {
                name: "svix.stream",
                version: "0.0.1"
            },
        },
        spans
    }
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.stream.events.create).

`config` describes the [service](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-name) and [scope attributes and definitions](https://opentelemetry.io/docs/concepts/instrumentation-scope/) that all tracing data are grouped under.

`spans` is an array of [OpenTelemetry spans](https://opentelemetry.io/docs/concepts/signals/traces/#spans). Each span has the following properties:

* `startTime` and `endTime`: These mark the start and end of the span. By default, they are set to the current timestamp, so you'll likely want to derive these from your events directly.
* `kind`: One of `"SERVER"`, `"CLIENT"`, `"PRODUCER"`, `"CONSUMER"`, or `"INTERNAL"` (`"INTERNAL"` is the default). For more details on the meaning behind these values, see [OpenTelemetry - Span Kinds](https://opentelemetry.io/docs/concepts/signals/traces/#span-kind)
* `name`: A string, denoting the name of the span.
* `attributes`: key-value pairing of attributes for the span. These can be any values you want associated with your span.
* `traceIdKey`: By default, each span is assigned it's own trace ID that is randomly generated by Svix.
However, you can specify a `traceIdKey` to derive a fixed key for the given span. This allows you to correlate multiple spans to the same trace.
* `spanIdKey`: Uniquely identifies a `span` with a fixed key. By default, Svix will use a randomly generated ID if left unspecified.
* `parentSpanIdKey`: Attaches the span as a child, to another span with the `spanIdKey` set to the same value. This allows you to set child spans.


# Example

To better understand how you can use OpenTelemetry Sinks, let's walk through an example use case where you want to send webhook dispatch telemetry to a cloud observability platform like Grafana.

Your service may produce events that look like the following:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
        {
            "eventType": "message.attempt",
            "payload": "{\"appId\": \"app_379\", \"msgId\": \"msg_1234\", \"attemptId\": \"atmpt_9876\", \"startTime\": \"2025-08-19T15:24:53.291Z\", \"endTime\": \"2025-08-19T15:24:56.291Z\" }"
        },
        {
            "eventType": "http.attempt",
            "payload": "{\"msgId\": \"msg_1234\", \"attemptId\": \"atmpt_9876\", \"startTime\": \"2025-08-19T15:24:54.291Z\", \"endTime\": \"2025-08-19T15:24:55.291Z\" }"
        },
        {
            "eventType": "message.attempt",
            "payload": "{\"appId\": \"app_379\", \"msgId\": \"msg_5678\", \"attemptId\": \"atmpt_1224\", \"startTime\": \"2025-08-19T15:24:51.291Z\", \"endTime\": \"2025-08-19T15:24:54.291Z\" }"
        },
        {
            "eventType": "http.attempt",
            "payload": "{\"msgId\": \"msg_5678\", \"attemptId\": \"atmpt_1234\", \"startTime\": \"2025-08-19T15:24:52.291Z\", \"endTime\": \"2025-08-19T15:24:53.291Z\" }"
        }
    ]
}'
```

Here, the events model webhooks being sent. Note that:
* We have two distinct messages being sent (distinct `msgId`s), each with their own attempt. Each attempt has a clear start and end time.
* The `http.attempt` happens within a `message.attempt`. In other words, `http.attempt` is a child span of `message.attempt`.

In order to ensure that each message is grouped into its own distinct trace, and that `http.attempt`s are correctly marked as child spans of `message.attempt`s,
we'll use the following transformation code.

```JavaScript
function handler(input) {
    const spans = input.events.map((event) => {
        const payload = event.payload
        return {
            // start and end times are extracted from the event directly.
            startTime: payload.startTime,
            endTime: payload.endTime,

            // We use the eventType as the name of the span,
            // as it makes it easier to identify which events map to
            // which spans in your OpenTelemetry platform.
            name: event.eventType,

            // We use the msgId as the traceIdKey, to ensure that all spans for the same
            // message are correctly grouped into the same trace.
            traceIdKey: payload.msgId,

            // Because we want to `http.attempt` to be a child span of the `message.attempt`, we
            // use the `attemptId` to mark the parent and child spans, respectively.
            spanIdKey: event.eventType === "message.attempt" ? payload.attemptId : undefined
            parentIdKey: event.eventType === "http.attempt" ? payload.attemptId : undefined,

            // Attributes can be anything you want. Here, we extract the important ID's from the event payload.
            attributes: {
              msgId: payload.msgId,
              appId: payload.appId,
              attemptId: payload.attemptId
            }
        }
    })

    // Note that your `service.name` has been configured to `my.webhook.service`, and each individual event sent to the Stream is treated as its own span.
    return {
        config: {
            serviceName: "my.webhook.service",
            scope: {
                name: "my.webhook.scope",
                version: "2.0"
            },
        },
        spans
    }
}
```

When we send these events to the stream, they'll be dispatched to your observability platform.

In this Grafana view, we can see `msg_1234` as its own isolated trace, with the `message.attempt` and `http.attempt` spans correctly grouped together, with the expected attributes.

![grafana-example](/img/stream/grafana-dashboard.png)

<OpenTelemetryProviderNotes />


<!-- Source: https://docs.svix.com/stream/sinks/poller -->

---
title: Polling Endpoint
---
# Polling Endpoint

Unlike other Sinks, Polling endpoints allow you to build clients to fetch events from the Stream directly, rather than having events pushed to you by Svix.

Like all Sinks, Polling Endpoint can be created in the Stream Portal or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "poller",
  "uid": "unique-identifier",
  "status": "enabled",
  "eventTypes": [],
  "metadata": {}
}'
```

As with other Sinks, you can specify which `eventTypes` you want the Sink to filter events on.

Unlike with other Sinks, the `batchSize`, `maxWaitSecs`, and transformations are ignored, as these settings aren't relevant for Polling endpoints.

## Usage
In the Stream Portal, event consumers will get a unique URL and an API key to iterate through the full list of events sent to their Svix Stream since the endpoint was created.

When creating a Polling Endpoint, consumers will get a unique URL like `https://api.svix.com/api/v1/stream/{stream_id}/sink/{sink_id}/events`

When first calling the endpoint, it will return an empty array and an iterator.

```json
{
  "data": [],
  "iterator": "eyJvZmZzZXQiOi05MjIzMzcyMDM2ODU0Nzc1ODA4LCJhZnRlciI6bnVsbH0",
  "done": false
}
```

Then, using the iterator in the next call, they can iterate through the events and poll for new ones.

```bash
curl \
  "https://api.svix.com/api/v1/stream/strm_30Vcjgt1o7mvmPbnhOQAB/sink/sink_30kXEU88euaFZlU1P5W0B?iterator=eyJv..." \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer sk_poll_*****.eu'
```

Events will be returned in the order they were posted to the Stream.


<!-- Source: https://docs.svix.com/stream/sinks/rabbitmq -->

---
title: RabbitMQ
---
# RabbitMQ

Events can be sent to RabbitMQ using the `rabbitMq` sink type.

Like all Sinks, RabbitMQ sinks can be created in the Stream Portal...

![rabbitmq-create](/img/stream/rabbitmq-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "rabbitMq",
  "config": {
    "uri": "amqp://user:password@rabbitmq.example.com:5672/my-vhost",
    "routingKey": "svix-events"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event in the batch is published to RabbitMQ as a separate message, using the `routingKey` from the config.

- `uri` — the AMQP connection URI for your RabbitMQ instance.
- `routingKey` — the routing key each message is published with.

# Transformations

By default, all `rabbitMq` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object containing the request body
 * @returns returns.payloads - The array of messages (strings) to send to the Sink. Each payload is a distinct message sent to the Sink.
 */
function handler(input) {

  const payloads = input.events.map((event) => JSON.stringify(event))

  return {
    payloads
  }
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

Each entry in the returned `payloads` array is published to RabbitMQ as a separate message. By default, each event is serialized to a JSON string containing its `payload` and `eventType`.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would publish two messages to your `routingKey`, with the following bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the message bodies, return your own array of strings in `payloads`. Each string becomes one message.


<!-- Source: https://docs.svix.com/stream/sinks/redshift -->

---
title: Amazon Redshift
---
# Amazon Redshift

Events can be sent to an Amazon Redshift table using the `redshift` sink type. Svix writes to Redshift through the [Redshift Data API](https://docs.aws.amazon.com/redshift-data/latest/APIReference/Welcome.html), and supports both Redshift Serverless and provisioned clusters.

Like all Sinks, Redshift sinks can be created in the Stream Portal...

![redshift-create](/img/stream/redshift-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "redshift",
  "config": {
    "region": "us-west-2",
    "accessKeyId": "AKIA3LIKMTLDNWBX2PPD",
    "secretAccessKey": "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",
    "workgroupName": "default",
    "dbName": "dev",
    "tableName": "events"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event batch is inserted into the configured Redshift table.

- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.
- `dbName` — the database to write to.
- `schemaName` — the schema that contains the table (optional).
- `tableName` — the table that receives the rows.

## Connection

How you point Svix at your Redshift depends on the deployment type:

- **Redshift Serverless** — set `workgroupName` to the name of your workgroup.
- **Provisioned clusters** — set `clusterIdentifier` to your cluster's identifier and `dbUser` to the database user to connect as.

```shell
# Provisioned cluster variant of the config block
  "config": {
    "region": "us-west-2",
    "accessKeyId": "AKIA3LIKMTLDNWBX2PPD",
    "secretAccessKey": "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",
    "clusterIdentifier": "my-cluster",
    "dbUser": "awsuser",
    "dbName": "dev",
    "tableName": "events"
  }
```

## Destination table

Without a transformation, Svix inserts each event into the table identified by `dbName`, `schemaName`, and `tableName` using two columns: `created_at` and `payload`. Svix sets `created_at` to the insert time and writes the raw event payload to `payload`.

The table must already exist before you enable the sink. For the default behavior, create it with:

```sql
CREATE TABLE events (
  created_at TIMESTAMP,
  payload VARCHAR(65535)
);
```

At the time of writing, `VARCHAR(65535)` is the largest allowable `VARCHAR` size in Redshift. If events with larger payloads are written to the stream, the sink will be disabled since these events can't be written to Redshift.

The `dbName`, `schemaName`, and `tableName` fields are only required when you're not using a transformation. With a transformation, the target table is named directly in your statement.

# Transformations

Redshift transformations build a parameterized SQL statement. The transformation returns the `statement` to run and the `bindings` it references.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing the SQL to run against Redshift.
 * @returns returns.statement - The SQL statement to execute. Reference parameters by name (e.g. :payload0).
 * @returns returns.bindings - The parameters referenced by the statement. Each binding is an object with a `name` and a `value`.
 */
function handler(input) {
    let bindings = [];
    let values = [];

    input.events.forEach((event, i) => {
        const name = `payload${i}`;
        bindings.push({ name: name, value: JSON.stringify(event.payload) });
        values.push(`(CURRENT_TIMESTAMP, :${name})`);
    });

    return {
        bindings: bindings,
        statement: `INSERT INTO events (created_at, payload) VALUES ${values.join(", ")};`
    };
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

`bindings` is an array of `{ name, value }` parameters, and the `statement` references them by name (e.g. `:payload0`). The statement is run against your database through the Redshift Data API. To write different columns, adjust the `bindings`, the `statement`, and your table to match.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The transformation above inserts two rows into your table.

| `created_at` | `payload` |
| --- | --- |
| `2025-07-21 14:23:18` | `{"email":"joe@enterprise.io"}` |
| `2025-07-21 14:23:18` | `{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"}` |


<!-- Source: https://docs.svix.com/stream/sinks/s3 -->

---
title: Amazon S3
---
# Amazon S3

Events can be sent to an S3 bucket using the `amazonS3` sink type.

Like all Sinks, S3 buckets can be created in the Stream Portal...

![s3-recent-events](/img/stream/s3-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.stream.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "amazonS3",
  "config": {
    "bucket": "my-s3-bucket-name",
    "region": "us-west-2",
    "accessKeyId": "AKIA3LIKMTLDNWBX2PPD",
    "secretAccessKey": "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"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event batch written to your S3 bucket will put a new object in the bucket.

# Transformations

By default, all `amazonS3` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON)
 * @param input.events[].eventType - The message event type (string)
 *
 * @returns Object describing what will be put to the bucket.
 * @returns returns.config
 * @returns returns.config.format - The format of the request object put to the bucket. Valid values are "jsonl", "json", or "raw" (Defaults to jsonl).
 * @returns returns.config.key - The name of the object that will be put to the bucket. This will be suffixed with a timestamp to avoid duplicate object names.
 * @returns returns.data - The array of events to send to the bucket. This will be formatted according to the format.
 */
function handler(input) {
    return {
        config: {
            format: "jsonl",
            key: "object-generated-by-svix"
        },
        data: input.events
    }
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.stream.events.create).

`config` describes the object put in the sink - the key name of the object, and the format of the object saved to the bucket.

By default, the actual object key is always suffixed with a timestamp after the transformations are run. This ensures each event batch is saved as a unique object in the bucket.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would result in the following object being uploaded to your bucket.

![s3-recent-events](/img/stream/s3-example.png)

And the files contents would match the jsonl format.

```jsonl
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

If you want to control the format of the object more precisely, you can use `config.format = "raw"`, and set `data` to a string of the exact file contents you want.


<!-- Source: https://docs.svix.com/stream/sinks/snowflake -->

---
title: Snowflake
---
# Snowflake

Events can be sent to a Snowflake table using the `snowflake` sink type.

Like all Sinks, Snowflake sinks can be created in the Stream Portal...

![snowflake-create](/img/stream/snowflake-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "snowflake",
  "config": {
    "accountIdentifier": "ab12345-xs67890",
    "userId": "my_user",
    "privateKey": "-----BEGIN PRIVATE KEY-----\nMII...bj5Nxr\n-----END PRIVATE KEY-----\n",
    "dbName": "my_database",
    "schemaName": "my_schema",
    "tableName": "my_table"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event batch written to your stream is inserted into the configured Snowflake table.

## Authentication

Svix authenticates to Snowflake using [key-pair (JWT) authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth). Generate an RSA key pair, assign the public key to a Snowflake user, and provide the matching private key in the sink config.

The `config` takes three credential fields:

- `accountIdentifier` — your Snowflake account identifier in `<organization>-<account>` form (e.g. `ab12345-xs67890`).
- `userId` — the Snowflake user the public key is assigned to.
- `privateKey` — the PEM-encoded private key.

## Destination table

Without a transformation, Svix inserts each event into the table identified by `dbName`, `schemaName`, and `tableName` using three columns: `id`, `created_at`, and `payload`. Svix generates a unique `id` for each row, sets `created_at` to the insert time, and writes the raw event payload to `payload`.

The table must already exist before you enable the sink, which you can create with the following sql:

```sql
CREATE TABLE my_database.my_schema.my_table (
  id TEXT,
  created_at TIMESTAMP,
  payload TEXT
);
```

If you use a transformation (below), you control the SQL that runs, so `dbName`, `schemaName`, and `tableName` become optional — the target table is named directly in your statement.

# Transformations

Snowflake Sinks shape each event batch into a SQL `INSERT` statement. The transformation returns the `statement` to run and the `bindings` it references.

For example, suppose you have a table with the following structure:

```sql
CREATE TABLE testdb.testschema.users (
  name TEXT,
  age INT
);
```

With these events written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
        {
            "payload": "{\"name\": \"John Smith\", \"age\": 34}",
            "eventType": "user.created"
        },
        {
            "payload": "{\"name\": \"Jane Doe\", \"age\": 47}",
            "eventType": "user.created"
        }
    ]
}'
```

To insert the new users into your `testdb.testschema.users` table, you'd write transformation code as follows:

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The event payload (string or JSON)
 * @param input.events[].eventType - The event type (string)
 *
 * @returns Object describing the SQL to run against Snowflake.
 * @returns returns.statement - The SQL statement to execute. Reference bindings by name (e.g. :id), matching the keys in `bindings`.
 * @returns returns.bindings - The bindings referenced by the statement. Each binding has a Snowflake `type` (e.g. "TEXT") and a column-oriented `value` array with one entry per row in the batch.
 */
function handler(input) {
    let bindings = {
        "name": { "type": "TEXT", "value": [] },
        "age": { "type": "FIXED", "value": [] },
    };

    input.events.forEach((event) => {
        let name = event.payload.name;
        let age = String(event.payload.age); // Note that Snowflake requires all values be sent as Strings
        bindings.name.value.push(name);
        bindings.age.value.push(age);
    });

    return {
        bindings: bindings,
        statement: "INSERT INTO TESTDB.TESTSCHEMA.users (name, age) VALUES (:name, :age);"
    };
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

`bindings` are column-oriented: each binding lists a Snowflake `type` and a `value` array holding one entry per row in the batch. The `statement` references them by name (`:name` and `:age`). For more information which types are allowed, see [Using bind variables in a statement.](https://docs.snowflake.com/en/developer-guide/sql-api/submitting-requests#using-bind-variables-in-a-statement)

Because the statement names the table directly, `dbName`, `schemaName`, and `tableName` are optional when a transformation is set. To write different columns, adjust the `bindings`, the `statement`, and your table to match.

The transformation above would insert two rows into your table.

![snowflake-output](/img/stream/snowflake-output.png)


<!-- Source: https://docs.svix.com/stream/sinks/sns -->

---
title: Amazon SNS
---
# Amazon SNS

Events can be sent to an Amazon SNS topic using the `sns` sink type.

Like all Sinks, SNS sinks can be created in the Stream Portal...

![sns-create](/img/stream/sns-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).

```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "sns",
  "config": {
    "topicArn": "arn:aws:sns:us-east-1:000000000000:my-topic",
    "region": "us-east-1",
    "accessKeyId": "AKIA3LIKMTLDNWBX2PPD",
    "secretAccessKey": "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"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event in the batch is published to the topic as a separate message.

- `topicArn` — the ARN of the SNS topic to publish to.
- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.

# Transformations

By default, all `sns` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON).
 * @param input.events[].eventType - The message event type (string).
 *
 * @returns Object containing the response.
 * @returns returns.messages - The array of SNS messages to send to the SNS topic.
 * @returns returns.messages[].payload - The content of the message (string).
 * @returns returns.messages[].subject - An optional subject of the message (string).
 */
function handler(input) {
  const messages = input.events.map((event) => ({
    payload: event,
  }));

  return {
    messages,
  };
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

Each entry in the returned `messages` array is published as a separate SNS message. The `payload` becomes the message body, and the optional `subject` becomes the SNS subject. By default, each event is published as its serialized JSON, with no subject.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would publish two messages to your topic, with the following bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the message bodies, or to set a subject, return your own array of `messages`. Each message's `payload` becomes the body of one SNS message, and `subject` is published as that message's SNS subject.

```JavaScript
function handler(input) {
  const messages = input.events.map((event) => ({
    payload: JSON.stringify(event.payload),
    subject: event.eventType
  }));

  return {
    messages,
  };
}
```

SNS accepts at most 10 messages per batch request, so larger batches are automatically split across multiple `PublishBatch` calls.


<!-- Source: https://docs.svix.com/stream/sinks/sqs -->

---
title: Amazon SQS
---
# Amazon SQS

Events can be sent to an Amazon SQS queue using the `sqs` sink type.

Like all Sinks, SQS sinks can be created in the Stream Portal...

![sqs-create](/img/stream/sqs-create.png)

... or [in the API](https://api.svix.com/docs#tag/Sink/operation/v1.streaming.sink.create).
```shell
curl -X 'POST' 'https://api.svix.com/api/v1/stream/strm_30XKA2tCdjHue2qLkTgc0/sink' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "sqs",
  "config": {
    "queueUrl": "https://sqs.us-east-1.amazonaws.com/000000000000/my-queue",
    "region": "us-east-1",
    "accessKeyId": "AKIA3LIKMTLDNWBX2PPD",
    "secretAccessKey": "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"
  },
  "uid": "unique-identifier",
  "status": "enabled",
  "batchSize": 1000,
  "maxWaitSecs": 300,
  "eventTypes": [],
  "metadata": {}
}'
```

Every event in the batch is sent to the queue as a separate message.

- `queueUrl` — the full URL of the SQS queue to send messages to.
- `region`, `accessKeyId`, `secretAccessKey` — the AWS region and credentials used to authenticate.

# Transformations

By default, all `sqs` Sinks come bundled with the following transformation code.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of events in the batch. The number of events in the batch is capped by the Sink's batch size.
 * @param input.events[].payload - The message payload (string or JSON).
 * @param input.events[].eventType - The message event type (string).
 *
 * @returns Object containing the response.
 * @returns returns.messages - The array of SQS messages to send to the SQS queue.
 * @returns returns.messages[].payload - The payload of the message (string).
 */
function handler(input) {
  const messages = input.events.map((event) => ({
    payload: event,
  }));

  return {
    messages,
  };
}
```

`input.events` matches the events sent in [`create_events`](https://api.svix.com/docs#tag/Event/operation/v1.streaming.events.create).

Each entry in the returned `messages` array is sent as a separate SQS message, with its `payload` used as the message body. By default, each event is sent as its serialized JSON.

For example, if the following events are written to the stream:

```shell
curl -X 'POST' \
  'https://api.svix.com/api/v1/stream/{stream_id}/events' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "events": [
            {
                "eventType": "user.created",
                "payload": "{\"email\": \"joe@enterprise.io\"}"
            },
            {
                "eventType": "user.login",
                "payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
            }
        ]
    }'
```

The default transformation code would send two messages to your queue, with the following bodies.

```json
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
```

```json
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
```

To control the message bodies, return your own array of `messages`. Each message's `payload` becomes the body of one SQS message.

SQS accepts at most 10 messages per batch request, so larger batches are automatically split across multiple `SendMessageBatch` calls.


<!-- Source: https://docs.svix.com/throttling -->

---
title: Endpoint Throttling
---
# Endpoint Throttling

While Svix can handle however many messages you send us, your customers' endpoints may not be able to. This is why the Svix API includes throttling of calls to customer endpoints.

This lets you send as many webhooks per second as you want without having to worry about overloading your customers' systems.


## How does it work?

You can set a throttling rate on both the application, which applies to all of the endpoints for that application, or the endpoint itself to only set it for that specific endpoint.

The throttling rate is defined as a limit for the number of messages per second to send to the endpoint. After the limit is reached, requests will get throttled so to keep a consistent rate under the limit.

Due to the nature of distributed systems the actual rate of messages can sometimes be slightly above the enforced throttling rate. So for example, if you set a throttling rate of 1,000 per seconds, an endpoint may potentially get messages at a rate of 1,050 or even higher.


## Setting the limits

You can set the throttling rate on either the application or each of its endpoint. The throttling rate is enforced per endpoint, so limits set on the application propagate to the endpoints and can be overridden by the endpoint specific settings.

### Setting application throttling rates

You can set the throttling rate on an application when [creating](https://api.svix.com/docs#operation/create_application_api_v1_app__post) or [updating](https://api.svix.com/docs#operation/update_application_api_v1_app__app_id___put) it using the `throttleRate` property. The value is the number of messages per second.

<CodeTabs items={["JavaScript","Python","Rust","Go","Java","Kotlin","Ruby","C#","PHP","CLI","cURL"]}>
<TabItem value="JavaScript">

```js
import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
const app = await svix.application.create({name: "Application name", throttleRate: 1000});
```

</TabItem>
<TabItem value="Python">

```python
from svix.api import Svix, ApplicationIn

svix = Svix("AUTH_TOKEN")
app = svix.application.create(ApplicationIn(name="Application name", throttle_rate=1000))
```

</TabItem>
<TabItem value="Rust">

```rust
use svix::api::{ApplicationIn, Svix, SvixOptions};

let svix = Svix::new("AUTH_TOKEN".to_string(), None);
let app = svix
    .application()
    .create(
        ApplicationIn {
            name: "Application name".to_string(),
            throttle_rate: Some(1000),
            ..ApplicationIn::default()
        },
        None,
    )
    .await?;
```

</TabItem>
<TabItem value="Go">

```go
import (
	svix "github.com/svix/svix-webhooks/go"
)

svixClient := svix.New("AUTH_TOKEN", nil)
app, err := svixClient.Application.Create(ctx, &svix.ApplicationIn{
    Name: "Application name",
    ThrottleRate: 1000,
})}
```

</TabItem>
<TabItem value="Java">

```java
import com.svix.models.ApplicationIn;
import com.svix.models.ApplicationOut;
import com.svix.Svix;

Svix svix = new Svix("AUTH_TOKEN");
ApplicationOut app = svix.getApplication().create(new ApplicationIn().name("Application name").throttleRate(1000));
```

</TabItem>
<TabItem value="Kotlin">

```kotlin
import com.svix.kotlin.models.ApplicationIn;
import com.svix.kotlin.Svix;

val svix = Svix("AUTH_TOKEN")
val applicationOut = svix.application.create(ApplicationIn(
    name = "Application name",
    throttleRate = 1000))
```

</TabItem>
<TabItem value="Ruby">

```ruby
require "svix"

svix = Svix::Client.new("AUTH_TOKEN")

application_out = svix.application.create(Svix::ApplicationIn.new({
    "name" => "Application name"
    "throttle_rate" => 1000}))
```

</TabItem>
<TabItem value="C#">

```csharp
using Svix;
using Svix.Model;
using Svix.Models;

var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
await svix.Application.CreateAsync(new EventTypeIn(
    name: "Application Name",
    throttleRate: 1000
))
```

</TabItem>
<TabItem value="PHP">

```php
$svix = new Svix('AUTH_TOKEN');

$app = $svix->application->create(
  ApplicationIn::create(
    name: 'Application name',
  )->withThrottleRate(1000)
);
```

</TabItem>
<TabItem value="CLI">

```shell
export SVIX_AUTH_TOKEN='AUTH_TOKEN'
svix application create '{ "name": "Application name", "throttleRate": 1000 }'
```

</TabItem>
<TabItem value="cURL">

```shell
curl -X POST "https://api.us.svix.com/api/v1/app/" \
    -H  "Accept: application/json" \
    -H  "Content-Type: application/json" \
    -H  "Authorization: Bearer AUTH_TOKEN" \
    -d '{"name": "Application name", "throttleRate": 1000}'
```

</TabItem>
</CodeTabs>


### Setting endpoint throttling rates

Similar to the application throttling rate, you can set the throttling rate on an endpoint when [creating](https://api.svix.com/docs#operation/create_endpoint_api_v1_app__app_id__endpoint__post) or [updating](https://api.svix.com/docs#operation/update_endpoint_api_v1_app__app_id__endpoint__endpoint_id___put) it using the `throttleRate` property. The value is the number of messages per second.


## Intended use

The throttling rate is intended to be used as a sort of a fuse to protect your customers' servers from sudden peaks in message traffic that they may not be able to withstand. With the limit, this peak is smoothened and spread over multiple seconds, sending messages at a rate your customers can handle.

One important thing to remember with throttling, is that if you are limiting to 1,000 messages per second and are consistently sending messages over that limit (e.g. 2,000 per second), the queue will get congested and you will be sending messages with infinitely increasing delays. We can alert you of such issues, and help you address them when they occur, though this is still something to be mindful of.


<!-- Source: https://docs.svix.com/transformations -->

---
title: Transformations
---
# Transformations

Transformations are a powerful Svix feature that allows the modification of certain webhook properties in-flight. When you enable Transformations, your customers can write JavaScript code on their endpoints that can change a webhook's HTTP method, target URL, and body payload.

## Enabling Transformations

Transformations can be enabled at the environment level. When you enable Transformations for an environment, your customers will be able to use Transformations on their endpoints.

To enable Transformations, navigate to the Settings page in the dashboard. Under the Environment Settings section, click General Settings, and then toggle the Enable Transformations switch. Your customers will need to reenter the Consumer App Portal for the change to take effect.

![Environment Settings page with the Enable Transformation toggle](/img/enable-transformations.png)

## Using Transformations

Once enabled for an environment, you customers can begin using Transformations by logging into the Consumer Portal, clicking on an endpoint, clicking into the Advanced tab, and scrolling down to the Transformations card:

![The Transformations card on an endpoint](/img/transformations-card.png)

An endpoint's Transformation can be enabled or disabled at any time by toggling the switch on this card.

Your customers can write Javascript code to edit an endpoint's Transformation, and test their code against an event type's payload or a custom payload to see the resulting webhook.

![Editing an endpoint's Transformation](/img/transformations-edit.png)

![Testing an endpoint's Transformation](/img/transformations-test.png)

### How to write a Transformation

Svix expects a Transformation to declare a function named `handler`. Svix will pass an object with the following properties to the function:

- `method`, a string representing the HTTP method the webhook will be sent with. It is always `"POST"` by default, and its only valid values are `"POST"`, `"PUT"`, or `"PATCH"`.
- `url`, a string representing the endpoint's URL. It can be changed to any valid URL.
- `payload`, which contains the webhook's payload as a JSON object. It can be changed as needed.
- `eventType`, a string representing the event type. Changes to it are ignored.
- `env`, (string) key to (string) value map of variables defined in the 'Variables' tab. Changes are ignored.
- `transformationsParams`, object passed to the parameter of the same name in the [create-message API call](https://api.svix.com/docs#tag/Message/operation/v1.message.create). Changes are ignored.

The Transformation must return the same object, but may modify its properties as described above.
In addition to the ones listed above, it can also set the following properties on the returned object:

- `cancel`, a boolean which controls whether or not to cancel the dispatch of a webhook. This value defaults to `false`. Note that canceled messages appear as successful dispatches.
- `headers`, an object with keys being HTTP header names and values being the associated header values. Headers set here take precedence over endpoint headers.

### An example Transformation

Suppose that sometimes, your customer wants to redirect webhooks to a custom URL instead of the endpoint's defined URL. They only want to do this redirect if a custom URL is present in the webhook payload. They can write a transformation like this:

```js
function handler(webhook) {
	if (webhook.payload.customUrl) {
		webhook.url = webhook.payload.customUrl;
	}
	return webhook;
}
```

Great, the webhook is redirected to the custom URL if the `customUrl` property exists on the payload. Otherwise, it is sent to the endpoint's defined URL.


<!-- Source: https://docs.svix.com/tutorials/api-webhook-management -->

---
title: Webhooks API for your customers
---

# Webhooks API for your customers

While most Svix customers use the [pre-built application portal](../app-portal.mdx) to let their webhook consumers manage their webhook subscriptions. In some scenarios it may be desirable to give webhook consumers the ability to manage their subscriptions using an API.

The most effective way to support this use case is by incorporating webhook management endpoints into your existing API. This allows your webhook consumers to use the same API they're already familiar with and continue using their existing authentication tokens.

You can achieve this by implementing thin wrappers around the Svix API that verify the authentication tokens and then make calls to the respective Svix APIs. Here is a small Python example showing how to wrap the [create endpoint API](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.create):

```python
from fastapi import FastAPI, HTTPException, Depends
from pydantic import BaseModel
from svix import Svix, EndpointIn
from .auth import get_authenticated_user, User

app = FastAPI()
svix = Svix("AUTH_TOKEN")

class EndpointRequest(BaseModel):
    url: str
    description: str
    # Add as many fields as you want here

@app.post("/endpoint")
def create_endpoint(data: EndpointRequest, user: User = Depends(get_authenticated_user)):
    try:
        return svix.endpoint.create(
            user.id,  # Using the user id as the app UID
            EndpointIn(url=data.url, description=data.description)
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
```


<!-- Source: https://docs.svix.com/tutorials/cli -->

---
title: Getting Started with the CLI
---
# Getting Started with the CLI

The Svix CLI is one of the fastest ways to interact with our API, which is especially useful during development.

With the Svix CLI you can interact with our webhook sending API, validate webhook payloads, quickly open our docs, and much more.

In this tutorial, we will learn how to install the Svix CLI and use it to send your first webhook message!

<Callout type="info">

This tutorial assumes you have already familiar with the [Svix webhooks service](https://www.svix.com). If this is your first time using Svix,
we recommend you first check out our [quickstart documentation](https://docs.svix.com/overview).

</Callout>
## Install the Svix CLI

Before you go any further, you need to [install the Svix CLI](https://github.com/svix/svix-cli).

<CLITabs>
<TabItem value="NPM">

To install the Svix CLI with [NPM](https://www.npmjs.com/), run:

```sh
npm install -g svix-cli
```

</TabItem>
<TabItem value="Homebrew">

To install the Svix CLI with [Homebrew](https://brew.sh), run:


```sh
brew install svix/svix/svix-cli
```

</TabItem>
<TabItem value="Scoop">

To install the Svix CLI with [Scoop](https://scoop.sh/), run:


```sh
scoop bucket add svix https://github.com/svix/scoop-svix.git
```

```sh
scoop install svix
```

</TabItem>
<TabItem value="macOS">

To install the Svix CLI on macOS without Homebrew:

1. Download the latest Darwin tar.gz file from https://github.com/svix/svix-cli/releases/latest

2. Extract the file: `tar -xvf svix_X.X.X_Darwin_x86_64.tar.gz`

2. Optionally, install the binary in a location where you can execute it globally (e.g., /usr/local/bin).

</TabItem>
<TabItem value="Linux">

To install the Svix CLI on Linux without a package manager:

1. Download the latest Linux tar.gz file from https://github.com/svix/svix-cli/releases/latest

2. Extract the file: `tar -xvf svix_X.X.X_Linux_x86_64.tar.gz`

3. Run the executable: `./svix`

</TabItem>
<TabItem value="Windows">

To install the Svix CLI on Windows without Scoop:

1. Download the latest Windows tar.gz file from https://github.com/svix/svix-cli/releases/latest

2. Extract the `svix_X.X.X_Windows_x86_64.tar.gz` file.

3. Run the `.exe` file

</TabItem>
</CLITabs>

## Authenticate with your Svix account

After installing the Svix CLI, you must authenticate with your Svix account before you can start running commands.

To do so, simply set your Svix Auth Token to the `SVIX_AUTH_TOKEN` env variable:

 - On macOS and Linux: `export SVIX_AUTH_TOKEN=<MY-AUTH-TOKEN>`
 - On Windows via command prompt: `set SVIX_AUTH_TOKEN=<MY-AUTH-TOKEN>`
 - On Windows via PowerShell: `$env:SVIX_AUTH_TOKEN = '<MY-AUTH-TOKEN>'`

## Create an application

You’re now ready to use the Svix CLI. To get started let's create a new application.

Each Svix CLI command accepts raw JSON input as either the first positional argument or piped via `stdin`.

We can create an application with the `application create` command:

```sh
svix application create '{"name": "My Application"}'
```

API commands also include convenience flags for common values to make it easier when handcrafting commands.
For example, the same application could have been created using the `--data-name` flag:

```sh
svix application create --data-name "My Application"
```

This command creates a new application on Svix and returns the raw application object as JSON.

## List your applications

Now that we've created an app we can list our existing apps with the following command:

```sh
svix application list
```

The list command by default returns the first 50 applications, you can change this limit by adding the `--limit` flag

```sh
# Get the first 100 applications
svix application list --limit 100
```

## Add an endpoint

Next let's add an endpoint to the application we created above.  The create command should have returned an Application ID.
Since the application name is not unique, we will need its ID to make changes.

Let's add a webhook endpoint with the url `http://example.com/webhook`. Every endpoint must have a version associated with it
to help you version your webhook API.  For this example we will set the version to `1`.

```sh
svix endpoint create <MY-APP-ID> \
    --data-url http://example.com/webhook \
    --data-version 1
```

## Send a message

Now that we have an application created and an endpoint configured to listen to messages from that app, we are ready to send our first
webhook message! Let's send a `user.created` event with the user's username and email.

```sh
svix message create <MY-APP-ID> \
    --data-eventType "user.created" \
    --data-payload '{
	    "username": "new_user",
	    "email": "new_user@example.com"
	}'
```

This message will now be sent to Svix and dispatched to all webhook endpoints listening to your application.

## Get creative

The Svix CLI has commands to interact with every part of the Svix API.

To get a complete list of commands, run `svix --help`.

Since each command accepts raw JSON input piped over `stdin`, you can chain Svix CLI commands together with other command line tools (like the popular JSON parser
[jq](https://stedolan.github.io/jq/)) to create powerful snippets to improve your workflow.

For example, to automatically open the dashboard for the app we created in step 3, on macOS you can run the following command:


```sh
svix application get <MY-APP-ID> | jq '.id' | xargs svix auth dashboard | jq '.url' | xargs open
```

With a slight modification, we can convert this one-liner to a shell function:

```zsh
function dashboard {
   svix application get "$1" | jq '.id' | xargs svix auth dashboard | jq '.url' | xargs open
}
```

Which you can run like so:

```zsh
dashboard <MY-APP-ID>
```


<!-- Source: https://docs.svix.com/tutorials/event-type-schema -->

---
title: Your first event type schema
---
# Your first event type schema

<Callout type="info">

**Prerequisites**

This guide assumes your familiar with the basics of [event types](../event-types) and the [App Portal](../app-portal).

</Callout>
The key to providing an easy webhook integration experience for your users lays in your event types.
The first thing your users are interested in seeing when integrating with you is: what events do you send and what information do the events provide.

It's very important that users can answer these two questions just by looking at your event types.

Let's walk through creating a new event type with Svix.

## Choosing an event type name

Let's imagine we are defining webhooks for when an organization within your service changes. Webhook consumers might be interested in when a user is added or removed from the organization. Or when the organization settings are changed. It's important to imagine what hypothetical endpoints a user might have listening to those events.

Your consumers might have one endpoint for organization member changes and one for listening to settings changes.

To make the event types discoverable, let's define them as follows:

- `organization.member.added`
- `organization.member.deleted`
- `organization.member.modified`
- `organization.settings.modified`

We have defined logic groups of event types and dot-delimited them. Svix understands this syntax and will group them visually in the App Portal UI.

## Defining the schema

Now we want our users to know just exactly what they can expect to see in the message payload for `organization.member.added`.

So let's add a schema to the event type:

![add-schema](/img/schema-add-schema.png)

### Option A. Using the visual editor

To get started with the visual editor, let's add some child fields. We need a field for `account_id`, `first_name`, `last_name` and `created_at`.

To create a new child field, click "Add child" from under the parent field. Each field row has the following properties:

- field name
- type
- title
- is required?

First, fill in the field names. You'll notice that the field titles will automatically update to match the field name. You can choose to override this with your own title if you'd like. Next, since all of these fields will always be present, make sure to check the "is required" checkboxes next to each field.

Finally, we can make the field data types more specific. `created_at` isn't just a string, we also know the format of the string. To specify the format, click the gear icon to the right of the field. You should see a list of configuration options for the `created_at` field. Change the format to `date-time` and add a description here if you'd like.

Once you've defined this basic schema, save your event type. The event type detail view will now show you a preview of the schema that matches the interface your users will see in the Event Catalog.

#### Adding a custom example

Next to the schema preview, you should see an example event defined. While this example is based on the schema parameters you defined, it might not be the best representation of reality.

For this reason, it's best to provide your own custom example.

To do so, go back into edit mode for the schema.

From there, click "Configure example". In the example textarea, you can change the example to be something like the following:

```json
{
  "account_id": "acct_0123456",
  "first_name": "Bruce",
  "last_name": "Wayne",
  "created_at": "2021-09-22T17:47:43.575Z"
}
```

Then click "Save" to see your changes reflected in the schema preview and the Event Catalog.

### Option B. Providing a JSONSchema

Instead of using the visual editor, you can also choose to provide your own JSONSchema. If you already have a JSONSchema (or JSONSchema-compatible definition) defined for your events, this is likely your fastest option.

When you are configuring your schema, you can switch to the "Code" tab to fill out your own JSONSchema (Draft 7) spec.

![schema-add-code](/img/schema-add-code.png)

After saving the raw JSONSchema, you can preview your event type to make sure that the schema matches what you expected.

## Event Catalog

After defining your event types and schemas, your users will be able to preview all your event types from the Event Catalog in the [App Portal](../app-portal), or optionally from the [published event catalog](../event-types#publishing-your-event-catalog) if enabled.


<!-- Source: https://docs.svix.com/tutorials/migrating-webhooks-to-svix -->

---
title: Migrating webhooks to Svix
---

Switching to Svix from your own home-grown webhooks system is usually straightforward. The intention of this tutorial is to help guide you through the process.

This tutorial assumes you already have a working Svix environment, and have successfully followed [the quickstart guide](../quickstart.mdx).

## Migration strategy

The recommended approach is to run both the existing legacy system and Svix in parallel, and gradually cut-over traffic on a customer by customer basis. That is, you would want to migrate full customers over rather than a percentage of traffic or some other mechanism.

To achieve this cut-over, you would want to locate the centralized location where all of your events are dispatched from (if you have one), or alternatively map all the places where webhooks are dispatched from.

Once located, you would want to change these to conditionally send webhooks to either your existing legacy system or Svix. The condition can use feature flags, a property on the target customer, a hardcoded list of customers, or whatever other mechanism you want to use to toggle which customers should use which system.

The next step is to copy over the data from your existing legacy system to Svix. You can do it using the Svix API as demonstrated [in the quickstart document](../quickstart.mdx). Namely, you'd want to [create a Svix application](https://api.svix.com/docs#tag/Application/operation/v1.application.create) for each of your customers, and [create the relevant endpoints](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.create) for each application.

It's easiest to start by cutting over traffic only for test accounts, or those of beta testers to make sure everything works as expected.

Once you see everything works, you can gradually toggle the rest of your customers to use Svix instead of the old system. Once done, you can bring down the old system and remove the code that calls it and the associated conditionals.

That's it! You can now safely delete all the thousands of lines of code and all of the infrastructure of your old systems. The transition is now complete!

Most of our customers gradually move over their customers over the span of a day or two. Though you can go as slow or fast as you're comfortable.

We help a lot of customers switch from their legacy home-grown systems to Svix, so please reach out if you have any questions. The team will be happy to help!

## Additional considerations

If you already use [Standard Webhooks](https://www.standardwebhooks.com/) as your signature scheme there's no additional work needed. Alternatively, if you use a different scheme, please reach out to the Svix team and we can provide instructions on how to make the transition seamless for your customers.


<!-- Source: https://docs.svix.com/tutorials/slack-connector -->

---
title: Configuring the Slack Connector
---
# Configuring the Slack Connector

<Callout type="info">

**Prerequisites**

This guide assumes your familiar with the basics of [event types](../event-types), the [App Portal](../app-portal) and [Connectors](../connectors).

</Callout>
[Connectors](https://docs.svix.com/connectors) make it easy for your customers to link your webhooks to popular services like Slack, Hubspot, or Microsoft Teams in just a few clicks—no code or new backend infrastructure required.

With the Slack connector, you can offer your users an easy-to-use way of integrating your webhooks with Slack, with almost no engineering effort on your part.

![Connectors diagram](/img/tutorials/slack-connectors/with-without-connectors.svg)

## Creating a Slack connector

1. Go to the [Connectors page](https://dashboard.svix.com/connectors) and click on "Configure Connector".

2. Add a description. This will be displayed to your users in the App Portal.

3. Select the event types this connector will support. You can choose specific event types that make sense for Slack, or select all of them.

4. Write the transformation code. This is the code that will be used to transform the webhook payload into a format that the Slack Incoming Webhooks API uses.

## Writing the transformation

Transformations allow the modification of certain webhook properties in-flight using Javascript code. The transformation is the key component that makes your connector work.

For the Slack connector, the transformation should make sure the webhook payload is formatted for the [Slack Incoming Webhooks API](https://api.slack.com/messaging/webhooks#posting_with_webhooks), for each of the event types you support (step 3).

For example, let's say you have two event types, `invoice.created` and `invoice.paid`, with the following schemas:

```json
{
  "invoice.created": {
    "type": "object",
    "properties": {
      "amount": {
        "type": "number"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "invoice.paid": {
    "type": "object",
    "properties": {
      "invoice_id": {
        "type": "string"
      },
      "amount": {
        "type": "number"
      }
    }
  }
}
```

Your transformation should `switch` on the `webhook.eventType` to determine how to use the payload and transform it for the Slack API.

```js
/**
 * @param webhook the webhook object
 * @param webhook.method destination method. Allowed values: "POST", "PUT", "PATCH"
 * @param webhook.url current destination address
 * @param webhook.eventType current webhook Event Type
 * @param webhook.payload JSON payload
 * @param webhook.cancel whether to cancel dispatch of the given webhook
 */
function handler(webhook) {
  switch (webhook.eventType) {
    case "invoice.created":
      webhook.payload = {
        text: `New invoice created: ${webhook.payload.amount}`
      };
      break;
    case "invoice.paid":
      // You can also use advanced formatting options (see https://api.slack.com/messaging/webhooks#advanced_message_formatting)
      webhook.payload = {
        text: `Invoice paid: ${webhook.payload.invoice_id}`,
        blocks: [
          {
            type: "section",
            text: {
              type: "mrkdwn",
              text: `Invoice paid: ${webhook.payload.invoice_id}`
            }
          },
          {
            type: "actions",
            elements: [
              {
                type: "button",
                text: {
                  type: "plain_text",
                  text: "View in dashboard"
                },
                url: `https://dashboard.invoices.com/invoices/${webhook.payload.invoice_id}`
              }
            ]
          }
        ]
      };
      break;
  }
  return webhook;
}
```

<Callout type="info">

Make sure your transformation works for the selected event types without any modifications, so your customers can use the connector in a few clicks. They will still be able to modify it if they want to.

</Callout>
## Testing the connector

Now that you've created your Slack connector, you can test it out in the App Portal.

[Create a sample application](https://docs.svix.com/quickstart#creating-a-consumer-application) and use the 'Preview App Portal' button in the Svix Dashboard.

In the App Portal, the new connector will be visible when creating a new endpoint.

![Slack connector in App Portal](/img/tutorials/slack-connectors/new-endpoint.png)

When creating an endpoint, your connector should work without any further changes, so just click create and test it!

![Testing](/img/tutorials/slack-connectors/testing.png)

After sending a test event, we should see the message directly in Slack:

![Slack message](/img/tutorials/slack-connectors/slack-notification.png)

And the message using advanced formatting:

![Slack message advanced](/img/tutorials/slack-connectors/advanced-formatting.png)

And that's it! In just a few clicks, your users will be able to connect their Slack account and start receiving notifications from your webhook events.

## Wrapping up

All we needed to do to setup the connector was select the event types we wanted to support and write the transformation. Svix takes care of the rest, so you can provide a one-click connection to Slack for your users.

Setting up connectors for the other supported services is just as easy. Check out the [Connectors docs](../connectors) to learn more.


<!-- Source: https://docs.svix.com/webhooks-autoconfig -->

# Webhooks AutoConfig

Webhooks AutoConfig is an easier way to configure and consume webhooks.

With AutoConfig, webhook consumers can set their webhook endpoint URL, event types, and other configuration in code
and AutoConfig will automatically ensure their settings are up to date. Configuration automatically changes when their
code changes without needing to go to the UI and reconfigure the endpoint.

## How it works

When AutoConfig is enabled in your environment, your users will be able to choose it as an option when creating an endpoint in the Application Portal.

![AutoConfig option in the Application Portal](/img/autoconfig/autoconfig-create.png)

The portal will issue an `AutoConfig token`, which can be used to configure the endpoint with the AutoConfig SDK.

The `AutoConfig token` also contains the endpoint signing secret, so the same instance can be used to verify webhook signatures.

Here's an example of how this looks like in code:

```js
import { AutoConfig } from "svix";

const webhook = new AutoConfig(AUTO_CONFIG_TOKEN, {
  filterTypes: ["invoice.paid", "user.created"],
  url: "https://api.us.example.com/webhooks/acme",
});

// Update the endpoint configuration
await webhook.subscribe();

// Same AutoConfig instance can be used to verify webhook signatures
const isVerified = webhook.verify(payload, headers);
```

To update the endpoint configuration, your customers simply need to change the AutoConfig options and call `subscribe()` again, which can be done as part of their
application startup or deployment process.

No manual steps in the Application Portal UI are needed, so the configuration is always in sync with the latest version of the application code.

For more information on how to receive webhooks using AutoConfig, see [Receiving with Webhooks AutoConfig](/receiving/webhooks-autoconfig).