Ruby on Rails

📘

In this tutorial you'll learn how to...

• Work with Lokalise API tokens
• Create webhooks with the Lokalise API
• Listen to webhooks events
• Handle incoming notifications

You can find the source code on GitHub.

Prerequisites

This guide assumes that you have already created a Lokalise project (if not, learn how to create a new project in this guide). Also, you'll need a read/write Lokalise API token; you can learn how to get one in the corresponding article. Alternatively, you can implement an OAuth 2 flow as explained the corresponding article and act on the user's behalf.

If you want to follow this guide locally on your computer, you need to have the following software installed:

• Ruby 2.7 or above
• Rails 6 or above
• Your favorite code editor
• Heroku CLI

Finally, please note that in order to listen and respond to webhook events, your app must be publicly accessible. In this tutorial, we'll deploy our app to Heroku (see below).

What we are going to build

We are going to create a simple application that will allow users to register webhooks in their Lokalise projects. The app will also listen to incoming notifications generated by these webhooks and react to them by sending API requests.

Preparing a new Rails app

Create a new Rails app by running the following command:

rails new LokaliseWebhooksDemo

This is going to create an application skeleton for you.

Open your Gemfile and modify it in the following way:

group :development do
  gem 'sqlite3', '~> 1.4'
end

group :production do
  gem 'pg', '~> 1.0'
end

gem 'ruby-lokalise-api', '~> 6.0'

cd into your project's directory and run:

bundle

Next, create a Procfile with the following contents:

web: bundle exec puma -C config/puma.rb

This file will be used on Heroku cloud hosting. If you are using a different hosting provider, you might need to take additional steps.

Finally, initialize a new Git repo and create a new Heroku app:

git init
git add .
git commit -m "Initial"
heroku create YOUR_APP_NAME

📘

Your app must be publicly accessible

If you run your Rails app locally (rails s) and provide localhost:3000/notify as a notification URL, it won't be possible to register a Lokalise webhook. That's because Lokalise sends a special "ping" request to the provided URL and expects to receive a 2xx status code. If the URL is not accessible, the webhook won't be created.

Registering webhooks

Now let's create a new controller inside the controllers/webhooks_controller.rb file:

require 'ruby_lokalise_api'

class WebhooksController < ApplicationController
  def new; end

  private

  def api_client
    @client ||= RubyLokaliseApi.client ENV['LOKALISE_API_TOKEN']
  end
end

This controller will be used to register new webhooks, thus we are creating a Lokalise SDK client here as well.

Next, we are going to create a new form inside the views/webhooks/new.html.erb file:

<h1>Register a new webhook</h1>

<%= form_with url: webhooks_path do |f| %>
  <%= f.label :project_id %>
  <%= f.text_field :project_id %>
  <%= f.submit "Register!" %>
<% end %>

Add the necessary routes to the config/routes.rb:

resources :webhooks, only: %i[new create]

root 'webhooks#new'

Next we'll add a create action to our WebhooksController, which should register a new webhook via the Lokalise API:

  def create
    api_client.create_webhook params[:project_id],
                              url: 'https://lokalise-webhooks-rails.herokuapp.com/webhooks/notify',
                              events: %w[project.key.added]

    redirect_to root_path
  end

Responding to notifications

Next up, let's add a new notify action to listen to all incoming events:

  skip_before_action :verify_authenticity_token, only: [:notify]

  # ...

  def notify
    if params[:event] == 'project.key.added'
      project_id = params[:project][:id]
      key_id = params[:key][:id]

      api_client.create_comments project_id, key_id, [
        { comment: '@Bob could you please double check this key to make sure it complies with our requirements?' }
      ]

      api_client.update_key project_id, key_id, is_hidden: true
    end

    head :ok
  end

So, if the event is project.key.added, we add a new comment for this key and hide it for all non-admins. Please note that your event handlers must respond to POST requests and return 2xx status codes. Otherwise, Lokalise will consider the webhook notification to be unsuccessful and will try to re-send failed notifications multiple times.

Please note that we are also skipping verification of the authenticity token for this action, which is mandatory. Alternatively, you can write a custom before_action to validate the X-Secret header (which we will see in a moment).

Add a new route to the config/routes.rb:

  resources :webhooks, only: %i[new create] do
    collection do
      post 'notify'
    end
  end

Testing it out

Now everything is ready! Let's publish our app to Heroku and add an environment variable with the Lokalise API token:

git add .
git commit -m "Finalized webhooks"
git push heroku master
heroku config:add LOKALISE_API_TOKEN=123abc
heroku open

Enter your Lokalise project ID in the text input and press "Register!".

Now open Lokalise, proceed to your project, and click "Apps" in the top menu. Find the "Webhooks" app, click on it, and then press "Manage". You'll see that a new webhook was registered for you:

Note the "X-Secret header" hidden value. You can use this value inside your app and compare it with the one sent to the notify action for extra protection (thus filtering out malicious requests).

Return to the Lokalise project editor and create a new translation key. Reload the page and make sure the key was hidden:

Click on the "Comments" button (the first button on the screen above) and make sure the comment is displayed properly:

This is it, great job!