Skip to main content

Quickstart

Learn how to send your first webhook using Svix.

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, allowing your customers to self-manage their own webhook endpoints, subscriptions, rate limits, and more.

Core concepts​

Svix is composed of three core building blocks: applications, endpoints, and messages.

Messages are the webhook messages being sent. They are most commonly JSON but Svix supports a variety of additional formats.

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

Prerequisites​

Create an API key​

Get your authentication token (AuthToken) from the Svix dashboard.

To interact with the Svix service, you'll need an API key. You can create one on the API Access page in the Svix dashboard.

API Access page

Install the Svix SDK (optional)​

npm install svix
// Or
yarn add svix

Create a consumer application​

As mentioned above, 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 uids.

In this example, we'll show how to create an application with the example-customer-123 UID using the create application API endpoint, though in practice you will set it to whatever unique identifier you use in your database.

import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN");
const app = await svix.application.create({
  name: "Application name",
  uid: "example-customer-123"
});

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, 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 and the application we created in the previous step (uid = example-customer-123):

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

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 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.

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.

tip

You can use the Svix Play webhook debugger and the Svix CLI to inspect, test and debug your webhooks during development.

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.

embedded iframe screen

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, and the application we created above (uid = example-customer-123):

const svix = new Svix("AUTH_TOKEN");
await svix.endpoint.create("example-customer-123", {
  url: "https://api.example.com/svix-webhooks/",
  description: "My main endpoint",
});

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.

Further reading​

Consuming webhooks documentation​

Please refer to the consuming webhooks 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.

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:

import { Svix } from "svix";

const svix = new Svix("AUTH_TOKEN", { serverUrl: "THE_SERVER_URL" });

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.