Skip to main content

Event Types

Each message sent through Svix has an associated event type. 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.

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.

Bulk Create

It's recommended to add the event types you are going to use ahead of time. You can do it using the scripts in the bulk creating event types section.

What your users will see

This is how choosing event types look like in the pre-built application portal:

Management UI screenshot

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: -, _, .
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.

Using event types

You can add, edit, and delete event types in the dashboard or through the API below.

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",
});

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.

schema-editor-basic

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

To learn more about creating schemas, check out our guide on adding your first 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!

Bulk creating event types

The easiest way to bulk-create event types is by just writing a simple script to load a pipe delimited CSV file or a JSON file with the event types and make the API requests.

Here is an example CSV file (without headers) of events:

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:

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();

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

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.

What it looks like

event-catalog-published

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 a feature flag 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:

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",
featureFlag: "beta-feature-a",
});

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 explicity allows them to see event types with the feature flag set during creation.

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);

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.

const svix = new Svix("AUTH_TOKEN");
await svix.eventType.update("user.signup", { featureFlag: null });
Important

Keep in mind that endpoints with no event type filtering will receive all messages regardless of feature flags. Also, users with knowledge of a feature flag-gated event type can subscribe to that event type regardless of feature flags. Feature flags only impact event types' visibility in the catalog and the API, not their deliverability.