Awesome Open Source
Awesome Open Source

Svix - Webhooks as a service

Website | Documentation | Community Slack

GitHub tag Build Status Server Security Twitter Follow Join our slack

Svix is the enterprise ready webhook service

Svix makes it easy for developers to send webhooks. Developers make one API call, and Svix takes care of deliverability, retries, security, and more. For more information, please refer to the Svix homepage.

PyPI Crates.io NPM version Gem Maven Central (Java) Maven Central (Kotlin) Nuget Packagist Version PkgGoDev

Documentation

You can find general usage documentation at https://docs.svix.com. For complete API documentation with code examples for each endpoint in all of our official client libraries head over to our API documentation site at https://api.svix.com.

Support & Community

To stay up-to-date with new features and improvements be sure to watch our repo!

Watch & Star our repo

Client Library Overview

Feature Breakdown
Language Officially Supported API Support Webhook Verification Other Notes
Go
Python
Typescript/Javascript
Java Async support planned. (If you use kotlin, checkout our kotlin library for coroutine support.)
Kotlin
Ruby
C# (dotnet)
Rust
PHP

Running the server

There are multiple ways to get the Svix server up running. Docker is probably the most common one, but you can choose the one that works best for you.

The Svix server is written in Rust , which means you can compile it into a static library for a variety of targets. Please refer to the building from source section below for more information.

Please refer to the server configuration section below for more information regarding the available settings.

Deployment

Docker

You can use the official Svix Docker image from Docker Hub. You can either use the latest tag, or one of the versioned tags instead.

You can either use the example docker-compose.yml file with docker-compose (easiest), docker swarm (advanced), or run the container standalone.

With Docker Compose

This alternative is the easiest because it will also boot up and configure redis and postgresql.

This assumes you have docker-compose installed.

cd server
docker-compose up

Standalone container

Running a standalone container is slightly more advanced, as it requires you to set some environment variables and have them pointing to your redis and postgres instances. You can pass individual environment variables to docker using the -e flag, or just create a file like development.env and use the --env-file flag like in the example below:

docker run \
  --name svix-server \
  -p 8071:8071 \
  --env-file development.env \
  svix/svix-server

Pre-compiled binaries

Pre-compiled binaries are available for released versions in the releases section.

Building from source

The Svix server is written in Rust and requires a Rust build environment.

If you already have one, you just need to run cargo build, otherwise, please please refer to the Svix server README for more information about building the server from source.

Runtime dependencies

The server requires the following runtime dependencies to work correctly:

  • A PostgreSQL server - for the storage of events.
  • An optional Redis server version 6.2.0 or higher - for the task queue and cache. Please note that it's recommended to enable persistence in Redis so that tasks are persisted across Redis server restarts and upgrades.

Server configuration

There are three ways to configure svix-server: environment vars, .env file, and a configuration file.

Configuration file

You can put a file called config.toml in the current working directory of svix-server and it will automatically pick it up. You can take a look at the example file for more information and a full list of supported settings: config.toml.

Here's a quick example of the most important configurations:

# The JWT secret for authentication - should be secret and securely generated
jwt_secret = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"

# The DSN for the database. Only postgres is currently supported.
db_dsn = "postgresql://postgres:[email protected]/postgres"

# The DSN for redis (can be left empty if not using redis)
redis_dsn = "redis://redis:6379"

# What kind of message queue to use.
queue_type = "redis"

Environment (variables or .env)

Alternatively, you can configure svix-server by setting the equivalent environment variables for each of the supported settings. The environment variables can either be passed directly or by setting them in a .env file.

The environment variables have the name name as the config names, but they are all upper case and are prefixed with SVIX_.

For example, the above example configuration would look like this if it was passed in the env:

# The JWT secret for authentication - should be secret and securely generated
SVIX_JWT_SECRET = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"

# The DSN for the database. Only postgres is currently supported.
SVIX_DB_DSN = "postgresql://postgres:[email protected]/postgres"

# The DSN for redis (can be left empty if not using redis)
SVIX_REDIS_DSN = "redis://redis:6379"

# What kind of message queue to use.
SVIX_QUEUE_TYPE = "redis"

Connection Pool Size

There are two configuration variables db_pool_max_size and redis_pool_max_size which control the maximum allowed size of the connection pool for PostgreSQL and Redis respectively.

They default to a max size of 20, but higher values can significantly increase performance if your database can handle it.

Authentication

Use valid JWTs generated with the correct secret as Bearer.

E.g:

Authorization: Bearer <JWT_TOKEN_HERE>

Either generate one using

svix-server jwt generate

Or if you are generating your own, make sure to use org_23rb8YdGqMT0qIzpgGwdXfHirMu as the sub field, and H256 as the algorithm.

Example valid JWT for the secret x (so you can see the structure):

// JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2NTUxNDA2MzksImV4cCI6MTk3MDUwMDYzOSwibmJmIjoxNjU1MTQwNjM5LCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.USMuIPrqsZTSj3kyWupCzJO9eyQioBzh5alGlvRbrbA
// Structure (when decoded):
{
  "iat": 1655140639,
  "exp": 1970500639,
  "nbf": 1655140639,
  "iss": "svix-server",
  "sub": "org_23rb8YdGqMT0qIzpgGwdXfHirMu"
}

Operational (incoming) webhooks

Operational webhooks are webhooks that you can subscribe to in order to get notified of important events occurring on the svix-server. The list of supported events is available in the webhooks section of the API reference.

The operational webhooks utilize Svix, and are controlled by a special account with the following ID: org_00000000000SvixManagement00. To turn operational webhooks on, set the operational_webhook_address config to point to your Svix server, and create a JWT for the special account. Once those are set, create an Application with the uid set to the org_id you're interested in, and add Endpoints for all of the events you'd like to subscribe to.

For example, for the default account, just create an app with the uid set to org_23rb8YdGqMT0qIzpgGwdXfHirMu.

Differences to the Svix hosted service

One of our main goals with open sourcing the Svix dispatcher is ease of use. The hosted Svix service, however, is quite complex due to our scale and the infrastructure it requires. This complexity is not useful for the vast majority of people and would make this project much harder to use and much more limited. This is why this code has been adjusted before being released, and some of the features, optimizations, and behaviors supported by the hosted dispatcher are not yet available in this repo. With that being said, other than some known incompatibilities, the internal Svix test suite passes. This makes them are already mostly compatible, and we are working hard on bringing them to full feature parity.

Development

Checkout our project specific development guides to get started hacking on Svix!

Contributing

Contributions are what makes the open source world go round! All contributions are very much welcomed and are greatly appreciated.

Please refer to the contribution guide for information on how to contribute.

A quick how to for contribution:

  1. Fork the project
  2. Create your feature branch (git checkout -b feature/some-feature)
  3. Make your changes
  4. Commit your changes (git commit -m 'Implement an amazing feature.')
  5. Push to the branch (git push origin feature/some-feature)
  6. Open a pull request

License

Distributed under the MIT License. See LICENSE for more information.

Backed By

Backed By YC & Aleph

Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,059,387
Python (806,773
Java (388,359
Typescript (245,991
Ruby (221,829
C Sharp (164,057
Go (158,174
Rust (57,501
Kotlin (46,431
Webhook (8,930
Webhook Server (34
Webhook Service (9