Send Webhooks with TypeScript (Express)

In this guide we will explain how to send webhooks from TypeScript (Express) using the Svix webhook sending service.

Svix simplifies sending webhooks from your service with robust deliverability and an amazing developer experience.

How to send webhooks with TypeScript + Svix

  1. Create a Svix account and get your authentication token
  2. Create an application to send webhooks to using the create application API
  3. Send webhooks to your customers using the create message API

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

TypeScript support in Svix

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

The library works for Node.js, Deno, and the browser.

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. Unreliable user endpoints fail or hang more often than you think. You need to monitor the deliverability to make sure your webhook service is reliable. Webhooks come with a myriad of security implications, such as SSRF, replay attacks, unauthenticated webhook events, and 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 all the information needed to start using Svix.

Main concepts

Svix has three important entities you will be interacting with:

  • message: 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 to easily interact 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 will 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 will 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 instead.

import { Svix } from "svix";

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

Send webhooks (messages)

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.

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>

You can find full details in the application portal docs.

Helping your users consume webhooks

In addition to helping you send webhooks to your users, we also provide several resources to make it easy for your users to receive webhooks 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.

We also offer a set of open-source libraries that make webhook verification very simple.

Finally, Svix Play provides users with a unique and persistent URL to easily inspect, test, and debug incoming webhooks.

Further reading

That's it! We covered everything you need to know in order to integrate Svix with your service. There are many more APIs that you can use to improve the experience of your users or your own development team. Two such examples are event types and the Svix CLI. For the most up to date information please refer to the Svix docs.

If you have any questions, or you just want to chat, please join the Svix Slack community.

Related articles

You may also be interested in reading the following related guides: