Introduction to Webhook Relay

May 15, 2017, by Karolis Rusenas

webhooks

Webhook Relay was created to solve one problem - simplify communication between systems by providing a webhook delivery system to applications that are running in internal networks.

While I was working on multiple different projects I noticed that if you have an internal
system that depends on a Github (or any other public SCM) repository - you either have to poll or
somehow notify your system when to poll since using webhooks is not an option.

While polling is an option in some cases - it can be quite limiting since you have to wait for several minutes for your changes to be picked up by internal CI or other system. So the feedback loop increases and productivity drops. There is just no excuse for this waiting time as nothing is happening and people get bored.

Polling simply does not scale. And everyone wants to scale in 2017. Imagine a system that has to check tens or hundreds of repositories every minute - you would almost instantly reach the rate limits and start looking for other solutions.

How does Webhook Relay work?

First of all, register and get access token here.

Basic 3 steps are required:

  1. In the buckets page, inputs and outputs are defined. Create at least one input and one output (where webhook should be relayed, i.e. https://127.0.0.1:8000/github-webhook/).
  2. In your repository go to settings page and then webhooks (https://github.com/[user]/[repo]/settings/hooks) and add the address from previous step. It looks something like this: https://my.webhookrelay.com/v1/webhooks/61798116-42ac-4fa4-b731-a3d488a4617a
  3. Get the latest relay clientand start it in internal network (i.e. your laptop). It opens a reverse tunnel and maintains a long lived connection. Agent should also be able to reach https://127.0.0.1:8000/github-webhook/. Since agent is establishing connection from inside there is no need to configure firewalls or open ports.

That’s it. Based on a user supplied token the agent will be mapped to a corresponding user and it will start receiving
incoming webhooks with desired destinations so it can start forwarding.

So the workflow looks like:

Webhooks

I hope this article was useful. New articles incoming, stay tuned!

P.S. Login/Registration here