This page has everything you need to start sending webhooks with Svix.
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
messagesare 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
endpointsand each message sent to that application will be sent to all of them (unless they are not subscribed to the sent event type).
Get your authentication token (
AuthToken) from the Svix dashboard.
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.
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.
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.
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.
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.
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.
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.
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.
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.