mailgun_webhooks 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Michael Guterl
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,45 @@
+# Mailgun Webhooks
+
+Add support for acting on Mailgun webhooks to your Rack or Rails application.
+
+## Rails Installation
+
+Add `gem 'mailgun_webhooks'` to your Gemfile.
+
+Setup `config/initializers/mailgun.rb`
+
+```ruby
+MailgunWebhooks.api_key = "yourapikeyfrommailgun"
+MailgunWebhooks.api_host = "yourdomain.com"
+```
+
+## Rack Installation
+
+If you wish to use MailgunWebhooks outside of Rails, you can leverage the same middleware used to provide Rails integration. Just add `MailgunWebhooks::App` to your middleware stack.
+
+```ruby
+use MailgunWebhooks::App
+```
+
+## Webhooks
+
+By default your application will listen for webhook payloads on `/mailgun`.  You can change this by setting `MailgunWebhooks.endpoint`.
+
+```ruby
+MailgunWebhooks.endpoint = '/mailgun_webhooks'
+```
+
+In order to customize how your application reacts to webhooks you can define the behavior using `Mailgun.on`.
+
+```ruby
+MailgunWebhooks.on(:bounced) do |data|
+  # Do something with the incoming data. Check the documentation for details:
+  # http://documentation.mailgun.net/user_manual.html#events-webhooks
+
+  if (user = User.find_by_email(data['recipient'])
+    user.update_attribute(:email_bounced_at, Time.now)
+  end
+end
+```
+
+**NOTE** It is important to recognize that the hash passed to the block is just a Hash and not a HashWithIndifferentAccess so you have to access the keys as strings, not symbols.

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'MailgunWebhooks'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/mailgun_webhooks.rb

@@ -0,0 +1,68 @@
+require 'mailgun_webhooks/signature'
+require 'mailgun_webhooks/webhook_registry'
+require 'mailgun_webhooks/rack'
+
+if defined? ::Rails
+  require 'mailgun_webhooks/rails/railtie'
+end
+
+module MailgunWebhooks
+  # Public: Base class for any errors raised from within MailgunWebhooks.
+  Error = Class.new(StandardError)
+
+  # Public: Error raised when signature is invalid.
+  InvalidSignature = Class.new(Error)
+
+  class << self
+    # Public: The Mailgun API key.
+    #
+    # Returns a String.
+    attr_accessor :api_key
+
+    # Public: The Mailgun API host.
+    #
+    # Returns a String.
+    attr_accessor :api_host
+
+    # Public: The endpoint for webhooks.
+    #
+    # Returns a String.
+    attr_accessor :endpoint
+  end
+
+  # Set default endpoint.
+  self.endpoint = '/mailgun'
+
+  # Make MailgunWebhooks behave like a singleton.
+  extend self
+
+  # Public: Add a webhook to the registry.
+  #
+  # Returns nothing.
+  def on(webhook, &block)
+    webhooks.on(webhook, &block)
+  end
+
+  # Public: Verify the signature of the data and trigger the webhook if it is
+  # valid. Raise InvalidSignature if the data signature is not valid.
+  #
+  # Returns nothing.
+  def trigger(webhook, data)
+    raise InvalidSignature unless verify_signature(data)
+
+    webhooks.trigger(webhook, data)
+  end
+
+  # Public: Helper method to check the validity of the data.
+  #
+  # Returns a boolean.
+  def verify_signature(data)
+    Signature.valid?(data.merge(:api_key => api_key))
+  end
+
+  # Internal: A WebhookRegistry instance.
+  def webhooks
+    @webhooks ||= WebhookRegistry.new
+  end
+
+end

data/lib/mailgun_webhooks/rack.rb

@@ -0,0 +1,21 @@
+module MailgunWebhooks
+  class Rack
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = ::Rack::Request.new(env)
+      params = request.params
+
+      if request.path == MailgunWebhooks.endpoint
+        MailgunWebhooks.trigger(params['event'], params)
+        [200, {}, []]
+      else
+        @app.call(env)
+      end
+    end
+
+  end
+end

data/lib/mailgun_webhooks/rails/railtie.rb

@@ -0,0 +1,9 @@
+module MailgunWebhooks
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "mailgun_webhooks.insert_middleware" do |app|
+        app.config.middleware.use "MailgunWebhooks::Rack"
+      end
+    end
+  end
+end

data/lib/mailgun_webhooks/signature.rb

@@ -0,0 +1,22 @@
+require 'openssl'
+
+module MailgunWebhooks
+  class Signature
+    # Public: Verifies the incoming data according to the MailgunWebhooks specs:
+    # http://documentation.mailgun.net/user_manual.html#events-webhooks
+    #
+    # Returns a boolean.
+    def self.valid?(data)
+      signature = data.fetch('signature')
+      api_key   = data.fetch('api_key')
+      timestamp = data.fetch('timestamp')
+      token     = data.fetch('token')
+      digest    = OpenSSL::Digest::Digest.new('sha256')
+
+      signature == OpenSSL::HMAC.hexdigest(digest,
+                                           api_key,
+                                           '%s%s' % [timestamp, token])
+    end
+
+  end
+end

data/lib/mailgun_webhooks/version.rb

@@ -0,0 +1,3 @@
+module MailgunWebhooks
+  VERSION = "0.0.1"
+end

data/lib/mailgun_webhooks/webhook_registry.rb

@@ -0,0 +1,23 @@
+module MailgunWebhooks
+  class WebhookRegistry
+
+    def initialize
+      @hooks = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Public: Store a block by name for later execution.
+    #
+    # Returns nothing.
+    def on(webhook, &block)
+      @hooks[webhook.to_sym] << block
+    end
+
+    # Public: Execute all of the blocks associated with the webhook.
+    #
+    # Returns nothing.
+    def trigger(webhook, data)
+      @hooks[webhook.to_sym].each { |hook| hook.call data }
+    end
+
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: mailgun_webhooks
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Michael Guterl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &70309673687320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.3
+  type: :development
+  prerelease: false
+  version_requirements: *70309673687320
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &70309673686900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70309673686900
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: &70309673686440 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70309673686440
+description: Easily add Mailgun Webhook integration to your Rails or Rack application.
+email:
+- michael@diminishing.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mailgun_webhooks/rack.rb
+- lib/mailgun_webhooks/rails/railtie.rb
+- lib/mailgun_webhooks/signature.rb
+- lib/mailgun_webhooks/version.rb
+- lib/mailgun_webhooks/webhook_registry.rb
+- lib/mailgun_webhooks.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: http://github.com/mguterl/mailgun_webhooks
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3481488083271243959
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3481488083271243959
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Rails and Rack integration for Mailgun Webhooks
+test_files: []