Ruby SDK for CloudEvents

CloudEvents Ruby SDK

A Ruby language implementation of the CloudEvents specification.


  • Ruby classes for representing CloudEvents, including support for standard and extension attributes.
  • Support for serializing and deserializing from JSON Structure Format and JSON Batch Format.
  • Support for sending and receiving CloudEvents via HTTP Bindings.
  • Supports the CloudEvent 0.3 and CloudEvents 1.0 specifications.
  • Extensible to additional formats and protocol bindings, and future specification versions.
  • Compatible with Ruby 2.4 or later, or JRuby 9.2.x or later. No runtime gem dependencies.


Install the cloud_events gem or add it to your bundle.

gem install cloud_events

Receiving a CloudEvent in a Sinatra app

A simple Sinatra app that receives CloudEvents:

# examples/server/Gemfile
source ""
gem "cloud_events", "~> 0.1"
gem "sinatra", "~> 2.0"
# examples/server/app.rb
require "sinatra"
require "cloud_events"

cloud_events_http = CloudEvents::HttpBinding.default

post "/" do
  event = cloud_events_http.decode_rack_env request.env "Received CloudEvent: #{event.to_h}"

Sending a CloudEvent

A simple Ruby script that sends a CloudEvent:

# examples/client/Gemfile
source ""
gem "cloud_events", "~> 0.1"
# examples/client/send.rb
require "cloud_events"
require "net/http"
require "uri"

data = { message: "Hello, CloudEvents!" }
event = CloudEvents::Event.create spec_version: "1.0",
                                  id:           "1234-1234-1234",
                                  source:       "/mycontext",
                                  type:         "com.example.someevent",
                                  data:         data

cloud_events_http = CloudEvents::HttpBinding.default
headers, body = cloud_events_http.encode_binary_content event URI("http://localhost:4567"), body, headers

Putting it together

Start the server on localhost:

cd server
bundle install
bundle exec ruby app.rb

This will run the server in the foreground and start logging to the console.

In a separate terminal shell, send it an event from the client:

cd client
bundle install
bundle exec ruby send.rb

The event should be logged in the server logs.

Hit CTRL+C to stop the server.


Bug reports and pull requests are welcome on GitHub at


After cloning the repo locally, install the bundle, and install the toys gem if you do not already have it.

bundle install
gem install toys

A variety of Toys scripts are provided for running tests and builds. For example:

# Run the unit tests
toys test

# Run CI locally, including unit tests, doc tests, and rubocop
toys ci

# Build and install the gem locally
toys install

# Clean temporary and build files
toys clean

# List all available scripts

# Show online help for the "test" script
toys test --help

Code style

Ruby code in this library generally follows the Google Ruby Style Guide, which is based on "Seattle Style" Ruby.

Style is enforced by Rubocop rules. You can run rubocop directly using the rubocop binary:

bundle exec rubocop

or via Toys:

toys rubocop

That said, we are not style sticklers, and if a break is necessary for code readability or practicality, Rubocop rules can be selectively disabled.

Pull requests

We welcome contributions from the community! Please take some time to become acquainted with the process before submitting a pull request. There are just a few things to keep in mind.

  • Typically a pull request should relate to an existing issue. If you have found a bug, want to add an improvement, or suggest an API change, please create an issue before proceeding with a pull request. For very minor changes such as typos in the documentation this isn't necessary.
  • Use Conventional Commit messages. All commit messages should follow the Conventional Commits Specification to make it clear how your change should appear in release notes.
  • Sign your work. Each PR must be signed. Be sure your git and are configured then use the --signoff flag for your commits. e.g. git commit --signoff.
  • Make sure CI passes. Invoke toys ci to run the tests locally before opening a pull request. This will include code style checks.


Releases can be performed only by users with write access to the repository.

To perform a release:

  1. Update lib/cloud_events/version.rb with the new release version.

  2. Add an entry to The changelog entry must be headed by the version and release date, and must be consistent with the format of previous entries.

  3. Ensure the above changes are pushed to the GitHub master branch at

  4. Execute

    toys release trigger $VERSION

    where $VERSION is the version number (e.g. 0.1.0). This script will verify the version and changelog and will not proceed unless they are correctly formatted and the master branch is up to date. It will also check that all GitHub checks against the current commit have succeeded. If these checks pass, the script will create and push a release tag.

  5. A GitHub action will then perform the release within a few minutes. The GitHub actions dashboard will provide status information on the release workflow.

    If the release workflow fails, fix the problem, and then you will need to delete the release tag manually before triggering the release again.

For more information


Each SDK may have its own unique processes, tooling and guidelines, common governance related material can be found in the CloudEvents community directory. In particular, in there you will find information concerning how SDK projects are managed, guidelines for how PR reviews and approval, and our Code of Conduct information.


Copyright 2020 Google LLC and the CloudEvents Ruby SDK Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this software except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.