Webhook Relay

This week I have finally ended up researching about current state of API documentation as I decided to write one for Webhook Relay.

Few years ago I have worked a bit with Swagger spec but found the tooling quite incomplete and embedding wasn't as nice as their marketing wanted you to believe.

This time I have looked at:

• OpenAPI
• Swagger

Seems like both OpenAPI and Swagger can be converted from one to another, but I chose Swagger as it just seemed to be a safer choice.

Editor

I started with https://apiary.io but quickly discovered that the web editor is quite lacking, there are no features as instant validation or auto-completion. Looking at swagger editor I had the same feeling. Main problems with the online editors:

• not your typical development environment
• lack of auto-completion
• while they do have auto-save functionality, you can't compare it to Git

After a quick search in VSCode extension I have found swagger viewer: https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer. It offers pretty much the same functionality as a web version but changes can be seen instantly and you still have to keep all your favorite keyboard shortcuts :)

Embedding

Embedding seemed also quite a challenging step. There are lots of solutions, but you need to choose what's best for you:

• Swagger UI (https://github.com/swagger-api/swagger-ui) - probably one of the most popular approaches, although didn't find the styling nice and didn't want to invest time into creating a theme.
• A fantastic custom Swagger UI - https://github.com/jensoleg/swagger-ui but the project does seem to be abandoned.
• Apiary.io hosting - each project gets its own 4th level subdomain which is neat, but a bit unnecessary in our case as we already have documentation website.
• Spectacle (https://github.com/sourcey/spectacle) - seems to be popular and I think I was going for this one but in the changed my mind.

Honestly, I thought I will probably just have to go the theming approach, but I accidentally found this excellent project Redoc:

https://github.com/Rebilly/ReDoc

With Redoc whole integration looks like:

<div id="redoc"> </div>
  
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> 
<script>
    Redoc.init('https://raw.githubusercontent.com/webhookrelay/swagger-webhookrelay/master/swagger.yaml', {
        scrollYOffset: 60,
        hideDownloadButton: true
    }, document.getElementById('redoc'))
</script>

So, we have a winner :) The end result looks like this: https://webhookrelay.com/api-reference/ although it's still in progress, there are some missing API calls that need to be documented such as domain reservation, sub-account management and tunnel ingress rule configuration. Still, I think Swagger + Redoc is a great pair. Combined with hosting it on Github you end up with an end-to-end solution.

October was quite an interesting month. Due to new a niche (home automation) that I decided to approach or at least experiment with, I have managed to add several features that I have wanted to see from the beginning in Webhook Relay:

• TLS tunnels (https://webhookrelay.com/v1/guide/tls-tunnels.html) that enable secure connection from the browser straight to the user's agent. While it did support HTTPS before, with those tunnels our servers are doing the termination so in theory we could be forced to spy on customers, now we just can't :)
• Custom domains enables users to specify their own domain names (https://webhookrelay.com/v1/guide/http-tunnels.html#Custom-domains) which is quite useful and I have already got my first users enjoying this feature.
• Hass.io add-on: https://webhookrelay.com/v1/guide/home-automation. Probably the easiest way to access your Home Assistant without configuring NAT, firewalls. The challenge with this add-on was that it needs configuration to be received in a special way and absolute priority here is privacy, hence the focus on TLS tunnels.

All in all, I think October so far is really productive. Currently exploring Knative (https://cloud.google.com/knative/) as it might benefit a lot from a good integration with a tunneling service.

When I initially set out to build Webhook Relay I envisioned it as a tool for developers, to quickly prototype their integrations with webhook providers. Over the months of running the service, I have noticed that more and more people are starting to use it for relatively intensive use cases (processing more than 10-20k webhooks a day).

Majority of people say that over-engineering your product in early phases is unnecessary and you should focus more on discovering market fit or just make it look nice. But in times like this, I am quite happy that I have initially sunk more time into the development of my tech. In short, Webhook Relay is written in Go, Vue.js, uses Postgres and Redis for persistence & caching. It's running on GKE (managed Kubernetes on Google Cloud).

I might write a blog post on running your stack without spending too much and achieving high reliability (uptimerobot is at 100%)