This section provides an overview of the main concepts of Svix and how to use them.
In Svix you can create multiple
environment is completely isolated from others. It has different data, different settings, and different API keys, among others.
Webhooks are called
messages. You can use your API keys to send
application can have multiple
message sent to a specific application is sent to all of the relevant
endpoints (filtered by
event type and
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
UIDs can be used interchangeably with
IDs 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.
There are a variety of entities in Svix. 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.
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
some-user and then use it with the Svix API as follows:
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.
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, where an endpoint can choose to only subscribe to a limited set of events.
Like with applications, you can define a
uid for an endpoint which can then be used interchangeably in the API with the endpoint's
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 it attempts have been exhausted. Please refer to the retry schedule for more information.
Messages can have an associated
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 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 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.
You will need to create event types for them to be shown in the application portal and used by endpoints.
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
Some people create multiple
Production environments based on geographical regions e.g.
Production EU and