Using Webhooks with Rails

Question

I am unfamiliar with Webhooks but I feel like they are the right thing for my app.

I have the following documentation for FluidSurveys webhook

I understand how I can make the webhook through a POST request to their API, but I don't know how can I tell where the webhook is actually going to send the response. Can I pass any subscription url I want? e.g. https://www.myapp.com/test and is that where webhook will send the data? Also, after the webhook is created I'm not sure how to ensure my Rails app will receive the response that is initiated. I assume a controller method that corresponds with the url I provide to the webhook.

If I'm correct on the controller handling the webhook, what would that look like?

Any guidance is appreciated.

Answer 1

Webhooks hook into your app via a callback URL you provide. This is just an action in one of your controllers that responds to POST requests and handles the webhook request. Every time something changes to the remote service, the remote service makes a request to the callback URL you provided, hence triggering the action code.

I'll exemplify with the survey created event. You start by defining a callback action for this event, where you handle the request coming from the webhook. As stated here the webhook responds with the following body:

survey_creator_name=&survey_name=MADE+A+NEW+SURVEY&survey_creator_email=timothy@example.com&survey_url=http%3A%2F%2Fexample.com%2Fsurveys%2Fbob%2Fmade-a-new-survey%2F``

Let's leave the headers for now, they don't contain important information. The available body parameters (survey_creator_name, survey_name etc.) will reflect all details regarding the new survey available on the remote service. So let's write a callback action that handles this request:

class HooksController

  def survey_created_callback
    # If the body contains the survey_name parameter...
    if params[:survery_name].present?
      # Create a new Survey object based on the received parameters...
      survey = Survey.new(:name => params[:survey_name]
      survey.url = params[:survey_url]
      survey.creator_email = params[:survey_creator_email]
      survey.save!
    end

    # The webhook doesn't require a response but let's make sure
    # we don't send anything
    render :nothing => true
  end

end

Let's add the route for this (in config/routes.rb):

scope '/hooks', :controller => :hooks do
  post :survey_created_callback
end

This will enable the POST /hooks/survey_created_callback route.

Now you'll need to subscribe this callback URL to the Webhooks API. First you'll want to know which hooks are available to you. You do this by placing a GET request at /api/v2/webhooks/. In the response you'll find the event name, survey and collector parameters.

Finally, you subscribe to one of the previously listed hooks by placing a request to the POST /api/v2/webhooks/subscribe/ URL with the following contents:

{
  "subscription_url": "http://your-absolute-url.com/hooks/survey_created_callback",
  "event": "[EVENT NAME FROM THE HOOKS LIST]",
  "survey": "[SURVEY FROM THE HOOKS LIST]",
  "collector": "[COLLECTOR FROM THE HOOKS LIST]"
}

The response to this will be a code 201 if the hook was created successfully, or code 409, if a webhook for the same callback URL already exists. Or something else, if this went bad :)

You can now test the hook, by creating a survey on the remote service and then watch it getting replicated in your Rails app.

Hope this helps...