- Tom Hacohen
We have just released our new Kotlin libraries (including async), and to celebrate we are posting an up to date Kotlin guide. Enjoy!
In this guide we will show you how to send webhooks from Kotlin 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.
Kotlin support in Svix
You can use Svix using the Kotlin library as show 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, 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.
You can also refer to the documentation for full documentation of how to use 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).
Install the dependencies
Install the Svix client-side libraries for easy interacting 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 should 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 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 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 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.
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. 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:
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>
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
That's it! We covered everything you need to know in order to integrate Svix with your service. Though there are many more APIs that you can use to improve the experience of your users or your own development experience. 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.