Svix Implementation Guide: How to Launch Webhooks

We often get asked by prospective customers how long an integration with Svix usually takes. The answer is: it depends. We have seen small companies literally go from signup to production in a matter of hours, and some larger companies go to production within days.

With that being said, larger companies may take a bit longer when you include all of the additional work such as design documents, testing, and verification. If you're at a mid-market or enterprise company, expect to finish the integration within roughly two weeks, and factor in a couple additional weeks to go to a full production deployment.

In this blog post we will outline the common steps of a Svix integration to help you better understand some of the work involved and estimate your timeline.

Step 1: deciding what webhooks to send

Before you start sending webhooks you need to decide what webhooks you would like to send. Webhooks are a part of your API which means breaking them can be painful for both you and your customers. That's why being thoughtful about which webhooks you would like to send and starting conservative will make everything smoother down the line.

Many Svix customers migrate from an existing implementation, in that scenario this step is usually straightforward: just copy what you already have.

For those that are starting from scratch, we usually recommend starting small. Start with the highest impact event types that will help you get started. You don't need to start from supporting every possible event types, you can start with the ones your customers are most eagerly waiting for.

We previously wrote a blog post about webhook versioning where we outlined how not to break your webhooks schema. Following the same guidelines make sense here as well.

Step 2: figuring out where to hook into Svix

Once you know which events you would like to send, you need to decide where to send them from. That's usually where the event happens on your backend, among the business logic.

We usually see two approaches here. The first approach just calls Svix directly either from within the code directly or sometimes from a background task or thread. The second approach is adding all events to an internal queue or message bus, and have a worker (or Svix Bridge) read from it and send to Svix.

The first approach is easier for people who don't already have internal event driven infrastructure, though the second is better as it allows for automatic healing if there are any network issues between the sender and Svix.

Step 3: embedding the consumer application portal

An important part of every webhook system is letting your customers subscribe to events. If they can't subscribe, you won't know which events they care about and where to send them to. Additionally, due to the nature of webhooks, it's important to offer your customers visibility into delivery logs and other necessary webhook information.

Building this can be time consuming, so to make that easy Svix offers a pre-built consumer app portal which you can white-label, customize, and embed within your product with only a few lines of code. Most of our customers use the embedded portal, but some build their own using the Svix React library or our SDKs.

Embedding the application portal usually involves adding an authenticated backend endpoint on your end which you then use to initialize the embedded portal in your dashboard. This is usually very quick, with most of the time being spent on customizing the app portal to match your look and feel.

Step 4: configuring the environment and creating event types

At this point the integration is mostly done. All that's left is configuring a production environment, copying the API key, and creating event types.

It's good practice to have a separate (and clean) production environment for your production data. You can easily achieve this with Svix and choose which region you'd like your data to reside in (for data residency purposes).

As for configuring your environment: Svix supports a variety of knobs and toggles you can modify on your environment all the way from enabling transformations to requiring HTTPS in endpoint URLs. You can change the configurations on the Svix dashboard.

Last, but not least, you need to configure your event types. These event types are used in a variety of places, including sending test events and filtering delivery per endpoint. There are several ways to create event types: either manually through the UI, or automatically using either the OpenAPI import functionality, automating with a script, using Github Actions, or another method.

Step 5: testing and validation

Once you're done configuring the Svix environment it's time to test and validate the integration. This step varies significantly among our customers. Some companies manually verify the integration by checking that the data they send is the same as what they are expecting, while others also add automated testing (oftentimes using tools like the Svix Play API).

Given the minimal Svix API surface in the message delivery path (only one API call) and the configuration path (only one API call as well), it's usually very easy to verify that the integration works as expected. However, depending on the number of different event types, and various locations from which webhooks are sent, the time required for validation can vary.

Step 6: launching with customers

Once the testing and validation step is complete, it's time to launch with customers! Here too we see a variety of approaches. Some of our customers launch publicly after internal verification, while others have a more gradual rollout starting with a small subset of their customers and expanding over time.

At this point, our customers also add a webhooks section to their documentation, to help webhook consumers easily integrate and subscribe to events. Svix makes it easy by offering template documentation that you can copy-paste, modify, and use on your end (see our documentation recommendations).

[Optional]: moving over from an existing implementation

As mentioned, many of our customers switch from existing home-grown implementations. These migrations are easier than greenfield builds in some ways, and slightly more involved in others. They are easier because many of the decisions have already been made (for example which event types to send), but more involved as there are some considerations when it comes to maintaining signature compatibility. There are several ways to make this process smooth so please reach out if you need help!

The most common approach we see is for customers to first change their code to create the relevant Svix entities (e.g. "applications") in addition to their existing ones. Once that's done they write a script (we can help) to backfill existing entities or use our just-in-time functionality to create them only as needed. After that, they start cutting over traffic customer by customer, verifying that everything is going smoothly, until they reach 100% and can full deprecate their legacy system.

In conclusion

Like every software engineering task, the exact time it will take is "it depends". However, the above should give you the necessary context to evaluate how long it should take in your case. If you're not sure, two weeks is usually a reasonable estimate.

If you have any questions, or would like help with your integration, please contact us, we would be happy to help!

For more content like this, make sure to follow us on Twitter, Github, RSS, or our newsletter for the latest updates for the Svix webhook service, or join the discussion on our community Slack.