Send Webhooks with Kotlin (Ktor)
In this guide we will show you how to send webhooks from Kotlin (Ktor) using the Svix webhook service, and offer a state of the art 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.
Kotlin support in Svix
You can use Svix using the Kotlin library as shown in the examples below, or alternatively use the Svix REST API directly if you prefer.
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.
You can also refer to the documentation for all the information needed to start using Svix.
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
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).
Install the dependencies
Install the Svix client-side libraries to easily interact with the Svix API.
Gradle: Add this dependency to your project's build file:
Maven: Add this dependency to your project's POM:
<dependency> <groupId>com.svix.kotlin</groupId> <artifactId>svix-kotlin</artifactId> <version>0.30.0</version> </dependency>
Note: this version number is just an example, please always get the latest version.
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:
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 com.svix.kotlin.models.ApplicationIn; import com.svix.kotlin.models.ApplicationOut; import com.svix.kotlin.Svix; val svix = Svix("AUTH_TOKEN") val applicationOut = svix.application.create(ApplicationIn(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.
val svix = Svix("AUTH_TOKEN") svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", MessageIn( eventType = "invoice.paid", payload = mapOf<String, Any>( "id" to "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status" to "paid", "attempt" to 2 ), eventId = "evt_Wqb1k73rXprtTm7Qdlr38G"))
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:
val svix = Svix("AUTH_TOKEN") val dashboard = svix.authentication.dashboardAccess("app_Xzx8bQeOB1D1XEYmAJaRGoj0") // A URL that automatically logs user into the dashboard println(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.
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.
You may also be interested in reading the following related guides: