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 user on your platform.
  • 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).

For more information, please refer to the Overview section.

Getting started

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

Custom server URL

If you are using a non-EU region, you will need to set the correct server URL in the libs based on the one shown in the "API Access" page in the dashboard.

import { Svix } from "svix";

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

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.
  • payload: a JSON dictionary that can hold anything. Its content will be sent as the webhook content.

For example, the following code sends a webhook of type eventType, with the contents of payload as the body:

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

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.

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.

tip

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

Using the Appl Portal

Svix offers a pre-build application portal. 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 application portal docs.

Using the API

In addition to the App Portal, 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.

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.

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.