OneSpan Sign How To: Create a Callback Event Notification Listener in Ruby

In this blog post, I will show you how to create a simple callback event notification listener in the Sinatra Ruby framework. Sinatra is a Ruby framework for quickly creating web applications with minimal effort. Let's get straight into it!

The Code

In my example, I will be using Ruby 2.3.3. If you don’t already have it installed, you can download it from their official website, here. You will also need to download the Development Toolkit in order to use the JSON module. Included in the link is a tutorial on how to install the Developer Toolkit.

In order to receive callback event notifications, you will need a publicly accessible URL to hit and work. Your localhost server on its own will not. Ngrok is a very simple and easy to use tool that creates a secure tunnel on your local machine along with a public URL you can use for browsing your local site. This saves you the trouble of deploying your web application.

The complete example code is available on the Developer Community Code Share. The first thing you’ll want to do is install the 'json' and 'sinatra' module. Open your command prompt and enter the following line:

gem install json
gem install sinatra

Now, in your favorite text editor, create a new file name "listener.rb" and save it in a location of your choice. Go ahead and copy the code below. I will go over it in more detail further down.

require 'sinatra'
require 'json'

post '/event' do
  request_payload = JSON.parse(request.body.read)
  puts request_payload
  status 200
end

Now, let’s go over the code step-by-step. The first couple of lines imports the modules needed for this example.

require 'sinatra'
require 'json'

Next, we need to define our endpoint URL (i.e. http://localhost:4567/event) for OneSpan Sign to hit. There is a POST request handler called /event, which is going to serve all the requests from OneSpan Sign.

post '/event' do
  request_payload = JSON.parse(request.body.read)
  puts request_payload
  status 200
end

In this simple example, I will simply print the JSON payload to the console.

Running Your Code

Open your command prompt and change the current directory to the location where you saved your "listener.rb" file. Then, enter the following line:

ruby listener.py

Then, in a new command prompt window, change the current directory to the location when you saved your ngrok executable file and enter the following line:

ngrok http 4567 -host-header="localhost:4567"

Finally, login to your OneSpan Sign account and browse to the Admin page. Enter in the "Callback URL" field the URL to your callback listener (i.e. http://f3e93555.ngrok.io/event) and register for the "transaction complete" event. Finally, create, send, and complete a test package. You should be able to view the JSON sent by eSignLive printed in the command prompt window.

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://developer.OneSpanSign.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today