Skip to main content

This version of GitHub Enterprise was discontinued on 2023-07-06. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Configuring your server to receive payloads

Learn to set up a server to manage incoming webhook payloads.

Now that our webhook is ready to deliver messages, we'll set up a basic Sinatra server to handle incoming payloads.

Note: You can download the complete source code for this project from the platform-samples repo.

Writing the server

We want our server to listen to POST requests, at /payload, because that's where we told GitHub our webhook URL was. Because we're using ngrok to expose our local environment, we don't need to set up a real server somewhere online, and can happily test out our code locally.

Let's set up a little Sinatra app to do something with the information. Our initial setup might look something like this:

require 'sinatra'
require 'json'

post '/payload' do
  push = JSON.parse(
  puts "I got some JSON: #{push.inspect}"

(If you're unfamiliar with how Sinatra works, we recommend reading the Sinatra guide.)

Start this server up.

Since we set up our webhook to listen to events dealing with Issues, go ahead and create a new issue on the repository you're testing with. Once you create it, switch back to your terminal. You should see something like this in your output:

$ ~/Developer/platform-samples/hooks/ruby/configuring-your-server $ ruby server.rb
> == Sinatra/1.4.4 has taken the stage on 4567 for development with backup from Thin
> >> Thin web server (v1.5.1 codename Straight Razor)
> >> Maximum connections set to 1024
> >> Listening on localhost:4567, CTRL+C to stop
> I got some JSON: {"action"=>"opened", "issue"=>{"url"=>"...

Success! You've successfully configured your server to listen to webhooks. Your server can now process this information any way you see fit. For example, if you were setting up a "real" web application, you might want to log some of the JSON output to a database.

For additional information on working with webhooks for fun and profit, head on over to the Testing Webhooks guide.