FormSG Ruby SDK

Ruby SDK for integrating with form.gov.sg webhooks

Not using Ruby? Check out our sister SDKs:

Installation

Add this line to your application's Gemfile:

gem 'formsg-sdk'

And then execute:

$ bundle

Or install it yourself as:

$ gem install formsg-sdk

Pre-Requisite

Your will need to have libsodium (https://github.com/jedisct1/libsodium) installed in your hosting server. For local development purposes, you can read up more at the installation guide for RbNaCl.

Usage

Ruby on Rails

In Rails, add this as an initializer:

# config/initializers/formsg_sdk.rb

Formsg::Sdk.configure do |config|
  config.default_public_key = "3Tt8VduXsjjd4IrpdCd7BAkdZl/vUCstu9UvTX84FWw=" # Production Public Key
  config.default_form_secret_key = "<your form's secret key>"
  config.default_post_uri = "https://example.com/submission"
end

Note: You should probably store the tokens as environment variables.

Example:

# config/initializers/formsg_sdk.rb

Formsg::Sdk.configure do |config|
  config.default_public_key = ENV["FORMSG_PUBLIC_KEY"]
  config.default_form_secret_key = ENV["FORMSG_FORM_SECRET_KEY"]
  config.default_post_uri = ENV["FORMSG_POST_URI"]
end

Add this in your controller method:

# apps/controllers/formsg_controller.rb

class FormsgController < ApplicationController
  # You can inherit this controller from ActionController::API to avoid the CSRF token
  skip_before_action :verify_authenticity_token, only: [:submissions]

  def submissions
    # Step 1: Verify that this is a valid Webhook request from FormSG
    Formsg::Sdk::Webhook.new.authenticate(
      header: request.headers['HTTP_X_FORMSG_SIGNATURE']
    )

    # Step 2: Read the data param
    payload = submission_param
    Rails.logger.info "POST params: #{payload.inspect}"

    # Step 3: Decrypt the form submission
    # Get just the responses as a Hash
    result_hash = Formsg::Sdk::SubmissionService.decrypt_for(data: payload)
    Rails.logger.info "Submission Result (Hash): #{result_hash.inspect}"

    # Get the Submission & Responses as an object
    submission = Formsg::Sdk::SubmissionService.build_from(data: payload)
    Rails.logger.info "Submission Result (Object): #{submission.inspect}"

    head :ok
  rescue => e
    Rails.logger.error "Invalid Submission: #{e.message}"

    head 500
  end

  private

  def submission_param
    params.require(:data)
  end
end

Ensure your routes.rb has the new controller method.

# config/routes.rb

post "/submissions", to: "formsg#submissions"

Deploy your app to your hosting server.
Update your FormSG's Webhook Endpoint URL.
Test by submitting a new form.

Sinatra

Refer to the sample app in this repository.

Public Key

FormSG environment	Public Key in base64
production	3Tt8VduXsjjd4IrpdCd7BAkdZl/vUCstu9UvTX84FWw=
staging	rjv41kYqZwcbe3r6ymMEEKQ+Vd+DPuogN+Gzq3lP2Og=

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Manual installation

Follow instructions at rbnacl on how to install the libsodium dependency in your development computer.
For MacOS, when installing ffi, you might run into this issue:

Function.c:847:17: error: implicit declaration of function 'ffi_prep_closure_loc' is invalid in C99

You can fix it by adding the --disable-system-libffi option:
```
gem install ffi:x.x.x -- --disable-system-libffi
```

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/opengovsg/formsg-ruby-sdk.

License

The gem is available as open source under the terms of the MIT License.