Webhookr::Mandrill

This gem is a plugin for Webhookr that enables your application to accept webhooks from Mandrill.

Installation

Add this line to your application's Gemfile:

gem 'webhookr-mandrill'

Or install it yourself:

$ gem install webhookr-mandrill

webhookr is installed as a dependency of webhookr-mandrill. If you have not setup Webhookr, do so now:

rails g webhookr:add_route

Usage

Once you have the gem installed run the generator to add the code to your initializer. An initializer will be created if you do not have one.

rails g webhookr:mandrill:init *initializer_name* -s

Run the generator to create an example file to handle mandrill webhooks.

rails g webhookr:mandrill:example_hooks

Or create a mandrill handler class for any event that you want to handle. For example to handle unsubscribes you would create a class as follows:

class mandrillHooks
  def on_spam(incoming)
    # Your custom logic goes here.
    User.unsubscribe_newletter(incoming.payload.msg.email)
  end
end

For a complete list of events, and the payload format, see below.

Edit config/initializers/initializer_name and change the commented line to point to your custom Mandrill event handling class. If your class was called MandrillHooks the configuration line would look like this:

  Webhookr::Mandrill::Adapter.config.callback = MandrillHooks

To see the list of Mandrill URLs your application can use when you configure mandrill webhooks, run the provided webhookr rake task:

rake webhookr:services

Example output:

mandrill:
  GET   /webhookr/events/mandrill/19xl64emxvn
  POST  /webhookr/events/mandrill/19xl64emxvn

Mandrill Events & Payload

Events

All webhook events are supported. For further information on these events, see the mandrill documentation.

Mandrill Event	Event Handler
send	on_send(incoming)
hard_bounce	on_hard_bounce(incoming)
soft_bounce	on_soft_bounce(incoming)
open	on_open(incoming)
click	on_click(incoming)
spam	on_spam(incoming)
unsub	on_unsub(incoming)
reject	on_reject(incoming)

Payload

The payload is the full payload data from as per the mandrill documentation, converted to an OpenStruct for ease of access. Examples for the method call unsubscribe:

  incoming.payload.msg._id
  incoming.payload.msg.ts
  incoming.payload.msg.email
  incoming.payload.msg.sender
  incoming.payload.msg.subject
  incoming.payload.msg.opens
  incoming.payload.msg.tags
  incoming.payload.msg.state
  incoming.payload.msg.diag
  incoming.payload.msg.bounce_description
  incoming.payload.msg.template

Supported Service - mandrill

• http://help.mandrill.com/entries/21738186-Introduction-to-Webhooks

Works with:

webhookr-mandrill works with Rails 3.1, 3.2 and 4.0, and has been tested on the following Ruby implementations:

• 1.9.3
• 2.0.0
• jruby-19mode

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions. As a result of this policy, once this gem reaches a 1.0 release, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision. For example:

spec.add_dependency 'webhookr-mandrill', '~> 1.0'

While this gem is currently a 0.x release, suggestion is to require the exact version that works for your code:

spec.add_dependency 'webhookr-mandrill', '0.0.1'

License

webhookr-mandrill is released under the MIT license.

Author

• Gerry Power