Skip to content
Codebase Notification Protocols
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Codebase Notification Server

The Codebase notification server exists to dispatch notification requests from the Codebase application. The server consists of a number of 'protocols' which are defined in the protocols/ folder and represent each of the various services which can be invoked when actions are carried out within Codebase.

A protocol consists of a number of options which should be defined by the user developing the specific protocol. You can look at existing protocols to get an example of how things work.

Each time an action is carried out within Codebase - the system will automatically attempt to call the appropriate protocol within the notification server. This request will include the full payload containing information about the action which has been carried out in addition to the configuration options the user has specified for your application.

Creating a protocol

Creating a new protocol is quite easy. Simply create a new file in the protocols/ directory with a name which is representative of the service you are implementing. For example, if you wanted to create a Basecamp protocol, simply call it basecamp.rb.

Within the file there are a number of options, firstly, you need to specify a description of the protocol which defines exactly what it does. This is displayed to users within the Codebase interface when configuring your service with their account.

desc 'My awesome service which posts messages to Campfire each time somebody carries out'
desc 'an activity within my Codebase account'.

The desc method can be called multiple times to define a multiline description. It will be joined into one sentence when displayed to the user

Defining Fields required for your protocol

Define which fields are required for your protocol to function.

field :username, :required => true, :description => "Your username"
field :password, :required => true, :description => "Your password"
field :url, :description => "Your URL"

If a field is required, simply set the :required key to true. The description is displayed to users when configuring the protocol within the interface.

Defining additional validation rules

If you need to validate the user provided options, you can do so by defining a validation block as displayed below.

validation do |options, errors|
   errors << "You must eat carrots" unless options['foods'].include?('carrots')
   errors << "ID must be a number" unless options['id'] =~ /\A\d+\z/

Simply add text into the errors array. If the errors array is not empty, the protocol will not be invoked and will be cancelled.

Defining the protocol itself

So, the real hard work itself,

protocol :basecamp do |type, options, payload|
  ## do your thing

Inside the protocol block, you have access to the type which is a symbol representing which type of activity was carried out (e.g. new_ticket, push, deployment etc...). options contains the user-configuration options for the notification. payload contains the full data for the request. You can view the example payloads in test/examples/*.json. All data is presented to the payload block as a hash with keys as strings.

The protocol block should return either true or false to represent whether the protocol action was carried out successfully or not.

If you encounter an error, simply raise it.

raise Error, "Something terrible happened!"

Raised errors are not reported back to the user but are logged for investigation by the Codebase team.

Additional libraries

If you require any additional libraries for your protocol to function, firstly, ensure you require them at the top of your protocol file (e.g. require net/ssh) and, if it's a Gem, ensure you add it to the libraries Gemfile.

When you're finished...

When you're happy with your protocol, submit your data back to the Codebase team who will review it and push it into our systems.


Your protocol should include a logo. Logos should be placed in logos/*.gif. The image file itself should be 48x48.


If you have any questions or comments, feel free to drop an email to

Something went wrong with that request. Please try again.