Configuring your server for webhooks

Learn how 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.

Writing the server

We want our server to listen to POST requests, at /payload, because that's where we told TextMaster 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 Sinatra application to do something with the webhook's payload. Our initial setup might look something like this:

server.rb

require 'sinatra'
require 'json'

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

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

Start this server up with:

$ ruby server.rb

Since we set up our webhook to listen to word count completion on documents, go ahead and create a new project with at least one document and let the word count analysis complete. Switch back to your terminal, you should see something like this in your server's output:

$ ruby server.rb
== Sinatra (v2.0.8.1) has taken the stage on 4567 for development with backup from Puma
Puma starting in single mode...
* Puma version: 5.5.2 (ruby 2.6.6-p146) ("Zawgyi")
*  Min threads: 0
*  Max threads: 5
*  Environment: development
*          PID: 819
* Listening on http://127.0.0.1:4567
* Listening on http://[::1]:4567
Use Ctrl-C to stop
> I got some JSON: {"word_count"=>100, "title"=>"...

Congratulations! 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 and trigger business workflows.

Tips: When setting up production servers, we strongly advise on handling webhook payloads asynchronously. Payloads may include heavy pieces of text which might take time to process on your server. HTTP connections are dropped after 30 seconds.