New feature announcement: domain-based endpoints

By Karolis Rusenas · May 31, 2020

We are happy to announce that new domain-based input endpoints are now available for everyone to use.

domains, subdomains and paths

Some people have probably already noticed that you could see one more endpoint in your input settings - https://my.webhookrelay.com/v1/webhooks/xxxx (default one) and https://xxxx.hooks.webhookrelay.com which is our new one. Building on our new virtual host based router we can also finally allow input endpoints such as https://hooks.example.com (you can put in your own domain) and custom paths such as https://hooks.example.com/github, https://hooks.example.com/stripe, etc..

In this short article we will briefly look into what has changed and what kind of improvements we can expect.

Background

When Webhook Relay was initially built, path-based routing solved the issue for systems like Jenkins and pretty much anything else we have encountered. However, there were always some cases such as:

  • Sensitive payload signing schemes where URL path was also included, therefore sending webhooks to /v1/webhooks/xxxx and then receiving them on http://internal_server/api/hooks would result in an invalid signature.
  • Custom domains for endpoints.
  • A custom path so you don’t have to stay with the same input ID for life.

Domain vs path-based endpoints

First of all, path-based webhook endpoints such as https://my.webhookrelay.com/v1/webhooks/xxxx are not being deprecated, they have their use case and they already deliver millions of webhooks per day. However, for each endpoint, you will now be able to also assign custom subdomains and domains.

Custom subdomains

Input endpoints can also now utilize custom subdomains. Instead of having an endpoint such as https://x1scmzopk2ogxxty3qvb4o.hooks.webhookrelay.com you can now specify your own subdomain under .hooks.webhookrelay.com, for example https://dogfood-shop.hooks.webhookrelay.com. To get started, either click on “reserve domain” in your input details page or go to https://my.webhookrelay.com/domains and reserve it there. Once you have reserved it, you will be able to select it from the dropdown.

Custom domains (hooks.example.com going through Webhook Relay)

Just like with custom subdomains for webhook endpoints you will have to register your own domain either in input details page or here. Once it’s registered, select it from the dropdown in the input details page.
Then, go to your DNS provider and configure a CNAME record pointing at hooks.webhookrelay.com. On the first webhook, Webhook Relay will provision a free certificate for you.

Advantages

Main advantages of using custom domains for webhook forwarding:

  • 3rd party software (that sends webhooks) sometimes can’t deal with /v1/webhooks/… style endpoints so subdomains become an easy to use solution.
  • You can delete and re-create your inputs in another bucket. Previously, you had your unique input ID that couldn’t be moved.
  • Even less lock-in. If you are using your own domain, you can always configure it to point at a hole in your firewall instead of Webhook Relay :)
  • Whitelabel endpoints. With custom domains, your customers will not know that Webhook Relay is accepting requests and processing them, you can put your own domain.
  • Build your own APIs. With custom domains, paths and Functions you can create a simple API that can respond to some requests directly or pass them to your backend.

You can find more information on domain configuration in the webhook forwarding documentation.