Skip to main content

Quickstart

This page has everything you need to start sending webhooks with Svix.

Main concepts#

In Svix you have three important entities you will be interacting with:

  • messages: these are the webhooks being sent. They can have contents and a few other properties.
  • application: this is where messages are sent to. Usually you want to create one application for each of your users.
  • endpoint: endpoints are 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 (unless they are not subscribed to the sent event type).

Getting started#

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

Sending messages#

Creating an application#

Each of your users needs an associated application. The easiest way is to create a new application whenever a user signs up. In this section we will use the create application API endpoint to create an application.

You would need the application's ID when sending messages. You can either save the ID returned when creating the application, or set your own unique id (e.g. your user's username or internal database id) in the optional uid field and use that intsead.

Code example:

import { Svix } from "svix";
const svix = new Svix("AUTH_TOKEN");
const app = await svix.application.create({name: "Application name"});

Send a message#

We will now send a new message using the create message API endpoint. It accepts an app_id, which is the application's ID (or custom uid) from the previous section. In addition, it accepts the following fields (as part the json body):

  • eventType: an identifier denoting the type of the event. E.g. invoice.paid.
  • eventId: an optional unique ID for the event. This is useful if you want to map each message to unique events on your system. This is also used as an idempotency key.
  • payload: a JSON dictionary that can hold anything. Its content will be sent as the webhook content.

For example:

const svix = new Svix("AUTH_TOKEN");
await svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", {
"eventType": "invoice.paid",
"eventId": "evt_Wqb1k73rXprtTm7Qdlr38G",
"payload": {
"id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
"status": "paid",
"attempt": 2
}
});

Idempotentcy#

As mentioned above, the eventId is also used as an idempotency key. This means that if you send the same request (with the same eventId) more than once, only one message will be created. The rest of the attempts will be ignored.

This means that you can safely retry sending messages on errors (such as network errors) without worrying about duplicate messages being sent.

Add webhook endpoints#

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.

Using the management UI#

Svix offers a pre-build management UI. With one API call, you can give your users access to this UI and they can then add their own endpoints themselves.

More on that in the management UI docs.

Using the API#

In addition to the management UI, you can also use our API to add endpoints to your applications. To do so, you will use the create endpoint API.

For example:

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

The version number is an integer signifying the current version of the API. You can set it to 1 if you haven't started versioning your API yet.

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 admin UI. All of them are covered here.