Sending Webhooks With JavaScript

Cover image

In this guide we will show you how to send webhooks from JavaScript using the Svix webhooks service, and offer a state of the part webhooks solution in minutes. You can think of Svix as a sort of Twilio or SendGrid, but for webhooks.

If you don't need a tutorial and just want to get started, please consider reading the quickstart docs instead.

JavaScript support in Svix

You can either use the Svix REST API, or use the Svix JavaScript library as shown in the examples below. The library is fully typed and was built using TypeScript but it's also available for JavaScript.

Why Svix?

Webhooks require a lot more engineering time, resources and ongoing maintenance than you would first expect.

When building your own webhooks you have to deal with a lot of challenges, such as: unreliable user endpoints, which fail or hang more often than you think; monitoring and reliability of your webhook system; security implications which are unique to webhooks and much more.

This is where we come in. With Svix you can start sending webhooks in under five minutes, and we take care of all of the above and more.

Sending webhooks

Svix offers a REST API and a set of libraries for interacting with the service. This guide will show how to use them.

You can also refer to the documentation for full documentation of how to use 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).

Install the dependencies

Install the Svix client-side libraries for easy interacting with the Svix API.

yarn add svix

Get your authentication token

Before you can start making calls to the Svix API you need to get an authentication token. You can get it from the Svix dashboard.

The authentication token should look something like this: sk_ArDkP03FcvFfPvPgZwQg9BNpQMK1d2Bm.

Create an application per user

Applications are where messages are sent to. An application represents one of your users, so each of your users needs an associated application. The easiest way is to create a new application whenever a user signs up.

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.

import { Svix } from 'svix'

const svix = new Svix('AUTH_TOKEN')
const app = await svix.application.create({ name: 'Application name' })

Send messages (webhooks)

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. More information at the event types docs.
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.

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

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.

You can either give users access directly using the create endpoint API which is out of scope for this tutorial, or using the application portal, which is what we'll show here.

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.

You can then either redirect your users to this URL like this:

const svix = new Svix('AUTH_TOKEN')
const dashboard = await svix.authentication.dashboardAccess('app_Xzx8bQeOB1D1XEYmAJaRGoj0')
// A URL that automatically logs user into the dashboard
console.log(dashboard.url)

Or use the URL to embed the UI using an <iframe /> in your own dashboard like this:

<iframe
  src="http://app.svix.com/login#key=eyJhcHBJZCI6ICJhcHBfMXRSdFlMN3pwWWR2NHFuWTRRZFI1azE4eXQ0IiwgInRva2VuIjogImFwcHNrX2UxOUN0Rm5hbTFoOU1Gamh5azRSMTUzNUNSd05VSWI0In0="
  style="width: 100%; height: 100%; border: none;"
>
</iframe>

More on that in the application portal docs.

Helping your users consume your webhooks

In addition to helping you send webhooks to your users, we also help your users to easily verify the authenticity and security of the webhooks they receive from you.

We offer easy to use docs for how to safely consume webhooks which you can share with your users directly: Consuming Webhooks documentation.

As part of that we offer a set of open-source libraries that your users can use when consuming webhooks