intercom_event is a port of the excellent stripe_event to support intercom webhooks. Define subscribers to handle specific event types. Subscribers can be a block or an object that responds to #call
.
contributions are very welcome!
# Gemfile
gem 'intercom_event', git: 'https://github.com/Tongboy/intercom_event'
setup a webhook URL in intercom dev center
ultrahook or ngrok can be used for dev/testing
# config/routes.rb
mount IntercomEvent::Engine, at: '/my-chosen-path' # provide a custom path that matches what you setup in intercom
# config/initializers/Intercom.rb
IntercomEvent.configure do |events|
# https://developers.intercom.com/v2.0/reference#topics - has possible options
events.subscribe 'conversation.' do |event|
# Define subscriber behavior based on the event object
end
events.all do |event|
puts event.topic
puts event.data.type
puts event.data.item.type
# Handle all event types - logging, etc.
end
end
class CustomerCreated
def call(event)
# Event handling
end
end
class BillingEventLogger
def initialize(logger)
@logger = logger
end
def call(event)
@logger.info "Convo:#{event.type}:#{event.id}"
end
end
IntercomEvent.configure do |events|
events.all BillingEventLogger.new(Rails.logger)
events.subscribe 'user.created', CustomerCreated.new
end
IntercomEvent.subscribe 'conversation.user.' do |event|
# Will be triggered for any conversation.user.* events
end
At this time we aren't consuming/working with the intercom Hub secret - we should
If you'd like to ignore particular webhook events (perhaps to ignore test webhooks in production, or to ignore webhooks for a non-paying customer), you can do so by returning nil
in you custom event_retriever
. For example:
IntercomEvent.event_retriever = lambda do |params|
return nil if Rails.env.production? && !params[:livemode]
Intercom::Event.retrieve(params[:id])
end
IntercomEvent can be used outside of Rails applications as well. Here is a basic Sinatra implementation:
require 'json'
require 'sinatra'
require 'intercom_event'
IntercomEvent.subscribe 'user.created' do |event|
# Look ma, no Rails!
end
post '/_billing_events' do
data = JSON.parse(request.body.read, symbolize_names: true)
IntercomEvent.instrument(data)
200
end
Verifying the behavior of IntercomEvent subscribers can be done fairly easily by stubbing out the HTTP request used to authenticate the webhook request. Tools like Webmock and VCR work well. RequestBin is great for collecting the payloads. For exploratory phases of development, UltraHook and other tools can forward webhook requests directly to localhost. You can check out test-hooks, an example Rails application to see how to test IntercomEvent subscribers with RSpec request specs and Webmock. A quick look:
# spec/requests/billing_events_spec.rb
require 'spec_helper'
describe "Billing Events" do
def stub_event(fixture_id, status = 200)
stub_request(:get, "https://api.Intercom.com/v1/events/#{fixture_id}").
to_return(status: status, body: File.read("spec/support/fixtures/#{fixture_id}.json"))
end
describe "customer.created" do
before do
stub_event 'evt_customer_created'
end
it "is successful" do
post '/_billing_events', id: 'evt_customer_created'
expect(response.code).to eq "200"
# Additional expectations...
end
end
end
Semantic Versioning 2.0 as defined at http://semver.org.
- fix specs - they are very broken and haven't been ported from stripe_event
- enable intercom hub secret check
- add support for rails 4.x - intercom_event.rb instrument method needs to be modified to support the param differences