Creating webhooks

This page explains how to set up a webhook, to send requests to your server which will handle these events.

Finding your payload URL

To set up a webhook, you'll need to tell us where to send events. This endpoint should use HTTPS.

Third-party

The fastest way to get started is with a service that provides an endpoint to process webhooks for you. Even if you eventually plan on creating a custom integration, this will allow you to validate you can receive webhooks correctly, before you start to develop on your machine or connect to your server.

webhook.site shows you webhooks it receives. The 'Your unique URL' field is your payload URL. This is useful for understanding what you will receive and debugging connections.

zapier allows you to build workflows based on webhooks. This is a low-code way to build workflows that integrate with different tools.

Your machine

To connect your webhook to your systems, you'll want to write a custom integration. To get started on your machine, we need to be able to reach it.

To do this, open a remote tunnel that exposes a port on your computer. A quick way to do this is with localhost.run:

ssh -R 80:localhost:8080 [e-mail]

Alternatively, you can use ngrok if you have it installed:

ngrok http 8080

The tool you're using will print out a URL which will be your payload URL. This will likely look like a series of random letters and numbers, ending either lhr.life or ngrok.io.

If you are using the free plan of either of these services, this address may change over time, in which case you will need to update it in the Hypertune UI when it changes.

Details on how to handle requests are covered later in this guide.

Your server

If you've already got a server set up for receiving webhooks, the payload URL will be the full URL including the scheme and path to receive webhooks at, such as:

https://my-server.my-company.com/my-path-for-hypertune-webhooks

Make sure it's possible to reach this URL from the public internet, so it can accept connections from our servers.

Details on how to handle requests are covered later in this guide.

Note: The services mentioned above are not affiliated with us, nor do we make any guarantees regarding their security. If you expect your webhook payloads to be sensitive you should do appropriate due diligence on the services you use.

Configuring your webhook in the Hypertune UI

To set up a webhook connection, navigate to your project and click the Settings tab. Scroll down to the Webhooks section and click 'New Webhook'.

Webhook name

This is just to help you organise your webhooks, in case you're setting up multiple on your project. It doesn't affect webhook delivery.

Payload URL

This should be set to the payload URL you found above. Make sure it starts with https:// and is publicly resolvable and reachable.

Secret

This secret allows you to verify that requests sent to your endpoint are genuine. We'll generate a secret for you, but you can set your own. It should be set to a cryptographically secure randomly generated string.

Active

This is a toggle that allows you to activate or deactivate webhook subscriptions. Webhooks will receive events only if they are active.