munster 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +4 -0
- data/README.md +12 -0
- data/handler-examples/customer_io_handler.rb +36 -0
- data/handler-examples/revolut_business_v1_handler.rb +29 -0
- data/handler-examples/revolut_business_v2_handler.rb +42 -0
- data/handler-examples/starling_payments_handler.rb +25 -0
- data/lib/munster/base_handler.rb +17 -1
- data/lib/munster/jobs/processing_job.rb +1 -1
- data/lib/munster/models/received_webhook.rb +5 -0
- data/lib/munster/templates/munster.rb +16 -4
- data/lib/munster/version.rb +1 -1
- metadata +6 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 7d3f84bd06c033ef585c3282701915793b981142351824cc7bba2f41c5bcde4b
|
|
4
|
+
data.tar.gz: 9e614a61681b3bed5667905ae378a357fcfa96d85c79b7d85c32473c2b763c4f
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 616dc8e6585239309106444bb65de90d572e946e08479044459e5f8deb764d0d308d22da895152e3d7250345a81640f627ea72485daf17d6d51b03299d29f5c3
|
|
7
|
+
data.tar.gz: 369a9b8ce33c83e876836f652b57fc618a82e3028818531f6bc98d8732fad53cc7a926d6faf2ad8711c5e08ac3e0c9ec23de06a95b597087f86091dfb78e6240
|
data/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,10 @@ All notable changes to this project will be documented in this file.
|
|
|
3
3
|
|
|
4
4
|
This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
5
5
|
|
|
6
|
+
## 0.4.1
|
|
7
|
+
|
|
8
|
+
- Webhook processor now requires `active_job/railtie`, instead of `active_job`. It requires GlobalID to work and that get's required only with railtie.
|
|
9
|
+
- Adding a state transition from `error` to `received`. Proccessing job will be enqueued automatic after this transition was executed.
|
|
6
10
|
|
|
7
11
|
## 0.4.0
|
|
8
12
|
|
data/README.md
CHANGED
|
@@ -30,6 +30,18 @@ Mount munster engine in your routes.
|
|
|
30
30
|
mount Munster::Engine, at: "/webhooks"
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
+
Define a class for your first handler (let's call it `ExampleHandler`) and inherit it from `Munster::BaseHandler`. Place it somewhere where Rails autoloading can find it, and add it to your `munster.rb` config file:
|
|
34
|
+
|
|
35
|
+
```ruby
|
|
36
|
+
config.active_handlers = {
|
|
37
|
+
"example" => "ExampleHandler"
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Example handlers
|
|
42
|
+
|
|
43
|
+
We provide a number of webhook handlers which demonstrate certain features of Munster. You will find them in `handler-examples`.
|
|
44
|
+
|
|
33
45
|
## Requirements
|
|
34
46
|
|
|
35
47
|
This project depends on two dependencies:
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# This is an example handler for Customer.io reporting webhooks. You
|
|
2
|
+
# can find more documentation here https://customer.io/docs/api/webhooks/#operation/reportingWebhook
|
|
3
|
+
class Webhooks::CustomerIoHandler < Munster::BaseHandler
|
|
4
|
+
def process(webhook)
|
|
5
|
+
json = JSON.parse(webhook.body, symbolize_names: true)
|
|
6
|
+
case json[:metric]
|
|
7
|
+
when "subscribed"
|
|
8
|
+
# ...
|
|
9
|
+
when "unsubscribed"
|
|
10
|
+
# ...
|
|
11
|
+
when "cio_subscription_preferences_changed"
|
|
12
|
+
# ...
|
|
13
|
+
end
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
def extract_event_id_from_request(action_dispatch_request)
|
|
17
|
+
action_dispatch_request.params.fetch(:event_id)
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
# Verify that request is actually comming from customer.io here
|
|
21
|
+
# @see https://customer.io/docs/api/webhooks/#section/Securely-Verifying-Requests
|
|
22
|
+
#
|
|
23
|
+
# - Should have "X-CIO-Signature", "X-CIO-Timestamp" headers.
|
|
24
|
+
# - Combine the version number, timestamp and body delimited by colons to form a string in the form v0:<timestamp>:<body>
|
|
25
|
+
# - Using HMAC-SHA256, hash the string using your webhook signing secret as the hash key.
|
|
26
|
+
# - Compare this value to the value of the X-CIO-Signature header sent with the request to confirm
|
|
27
|
+
def valid?(action_dispatch_request)
|
|
28
|
+
signing_key = Rails.application.secrets.customer_io_webhook_signing_key
|
|
29
|
+
xcio_signature = action_dispatch_request.headers["HTTP_X_CIO_SIGNATURE"]
|
|
30
|
+
xcio_timestamp = action_dispatch_request.headers["HTTP_X_CIO_TIMESTAMP"]
|
|
31
|
+
request_body = action_dispatch_request.body.read
|
|
32
|
+
string_to_sign = "v0:#{xcio_timestamp}:#{request_body}"
|
|
33
|
+
hmac = OpenSSL::HMAC.hexdigest("SHA256", signing_key, string_to_sign)
|
|
34
|
+
Rack::Utils.secure_compare(hmac, xcio_signature)
|
|
35
|
+
end
|
|
36
|
+
end
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# This is for Revolut V1 API for webhooks - https://developer.revolut.com/docs/business/webhooks-v-1-deprecated
|
|
2
|
+
class RevolutBusinessV1Handler < Munster::BaseHandler
|
|
3
|
+
def valid?(_)
|
|
4
|
+
# V1 of Revolut webhooks does not support signatures
|
|
5
|
+
true
|
|
6
|
+
end
|
|
7
|
+
|
|
8
|
+
def self.process(webhook)
|
|
9
|
+
parsed_payload = JSON.parse(webhook.body)
|
|
10
|
+
topic = parsed_payload.fetch("Topic")
|
|
11
|
+
case topic
|
|
12
|
+
when "tokens" # Account access revocation payload
|
|
13
|
+
# ...
|
|
14
|
+
when "draftpayments/transfers" # Draft payment transfer notification payload
|
|
15
|
+
# ...
|
|
16
|
+
else
|
|
17
|
+
# ...
|
|
18
|
+
end
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
def self.extract_event_id_from_request(action_dispatch_request)
|
|
22
|
+
# Since b-tree indices generally divide from the start of the string, place the highest
|
|
23
|
+
# entropy component at the start (the EventId)
|
|
24
|
+
key_components = %w[EventId Topic Version]
|
|
25
|
+
key_components.map do |key|
|
|
26
|
+
action_dispatch_request.params.fetch(key)
|
|
27
|
+
end.join("-")
|
|
28
|
+
end
|
|
29
|
+
end
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# This is for Revolut V2 API for webhooks - https://developer.revolut.com/docs/business/webhooks-v-2
|
|
2
|
+
class RevolutBusinessV2Handler < Munster::BaseHandler
|
|
3
|
+
def valid?(request)
|
|
4
|
+
# 1 - Validate the timestamp of the request. Prevent replay attacks.
|
|
5
|
+
# "To validate the event, make sure that the Revolut-Request-Timestamp date-time is within a 5-minute time tolerance of the current universal time (UTC)".
|
|
6
|
+
# Their examples list `timestamp = '1683650202360'` as a sample value, so their timestamp is in millis - not in seconds
|
|
7
|
+
timestamp_str_from_headers = request.headers["HTTP_REVOLUT_REQUEST_TIMESTAMP"]
|
|
8
|
+
delta_t_seconds = (timestamp_str_from_headers / 1000) - Time.now.to_i
|
|
9
|
+
return false unless delta_t_seconds.abs < (5 * 60)
|
|
10
|
+
|
|
11
|
+
# 2 - Validate the signature
|
|
12
|
+
# https://developer.revolut.com/docs/guides/manage-accounts/tutorials/work-with-webhooks/verify-the-payload-signature
|
|
13
|
+
string_to_sign = [
|
|
14
|
+
"v1",
|
|
15
|
+
timestamp_str_from_headers,
|
|
16
|
+
request.body.read
|
|
17
|
+
].join(".")
|
|
18
|
+
computed_signature = "v1=" + OpenSSL::HMAC.hexdigest("SHA256", Rails.application.secrets.revolut_business_webhook_signing_key, string_to_sign)
|
|
19
|
+
# Note: "This means that in the period when multiple signing secrets remain valid, multiple signatures are sent."
|
|
20
|
+
# https://developer.revolut.com/docs/guides/manage-accounts/tutorials/work-with-webhooks/manage-webhooks#rotate-a-webhook-signing-secret
|
|
21
|
+
# https://developer.revolut.com/docs/guides/manage-accounts/tutorials/work-with-webhooks/about-webhooks#security
|
|
22
|
+
# An HTTP header may contain multiple values if it gets sent multiple times. But it does mean we need to test for multiple provided
|
|
23
|
+
# signatures in case of rotation.
|
|
24
|
+
provided_signatures = request.headers["HTTP_REVOLUT_SIGNATURE"].split(",")
|
|
25
|
+
# Use #select instead of `find` to compare all signatures even if only one matches - this to avoid timing leaks.
|
|
26
|
+
# Small effort but might be useful.
|
|
27
|
+
matches = provided_signatures.select do |provided_signature|
|
|
28
|
+
ActiveSupport::SecurityUtils.secure_compare(provided_signature, computed_signature)
|
|
29
|
+
end
|
|
30
|
+
matches.any?
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
def self.process(webhook)
|
|
34
|
+
Rails.logger.info { "Processing Revolut webhook #{webhook.body.inspect}" }
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def self.extract_event_id_from_request(action_dispatch_request)
|
|
38
|
+
# The event ID is only available when you retrieve the failed webhooks, which is sad.
|
|
39
|
+
# We can divinate a synthetic ID though by taking a hash of the entire payload though.
|
|
40
|
+
Digest::SHA256.hexdigest(action_dispatch_request.body.read)
|
|
41
|
+
end
|
|
42
|
+
end
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# This handler is an example for Starling Payments API,
|
|
4
|
+
# you can find the documentation here https://developer.starlingbank.com/payments/docs#account-and-address-structure-1
|
|
5
|
+
class StarlingPaymentsHandler < Munster::BaseHandler
|
|
6
|
+
# This method will be used to process webhook by async worker.
|
|
7
|
+
def process(received_webhook)
|
|
8
|
+
Rails.logger.info { received_webhook.body }
|
|
9
|
+
end
|
|
10
|
+
|
|
11
|
+
# Starling supplies signatures in the form SHA512(secret + request_body)
|
|
12
|
+
def valid?(action_dispatch_request)
|
|
13
|
+
supplied_signature = action_dispatch_request.headers.fetch("X-Hook-Signature")
|
|
14
|
+
supplied_digest_bytes = Base64.strict_decode64(supplied_signature)
|
|
15
|
+
sha512 = Digest::SHA2.new(512)
|
|
16
|
+
signing_secret = Rails.credentials.starling_payments_webhook_signing_secret
|
|
17
|
+
computed_digest_bytes = sha512.digest(signing_secret.b + action_dispatch_request.body.b)
|
|
18
|
+
ActiveSupport::SecurityUtils.secure_compare(computed_digest_bytes, supplied_digest_bytes)
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# Some Starling webhooks do not provide a notification UID, but for those which do we can deduplicate
|
|
22
|
+
def extract_event_id_from_request(action_dispatch_request)
|
|
23
|
+
action_dispatch_request.params.fetch("notificationUid", SecureRandom.uuid)
|
|
24
|
+
end
|
|
25
|
+
end
|
data/lib/munster/base_handler.rb
CHANGED
|
@@ -16,11 +16,27 @@ module Munster
|
|
|
16
16
|
webhook = Munster::ReceivedWebhook.new(request: action_dispatch_request, handler_event_id: handler_event_id, handler_module_name: handler_module_name)
|
|
17
17
|
webhook.save!
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
enqueue(webhook)
|
|
20
20
|
rescue ActiveRecord::RecordNotUnique # Webhook deduplicated
|
|
21
21
|
Rails.logger.info { "#{inspect} Webhook #{handler_event_id} is a duplicate delivery and will not be stored." }
|
|
22
22
|
end
|
|
23
23
|
|
|
24
|
+
# Enqueues the processing job to process webhook asynchronously. The job class could be configured.
|
|
25
|
+
#
|
|
26
|
+
# @param webhook [Munster::ReceivedWebhook]
|
|
27
|
+
# @return [void]
|
|
28
|
+
def enqueue(webhook)
|
|
29
|
+
# The configured job class can be a class name or a module, to support lazy loading
|
|
30
|
+
job_class_or_module_name = Munster.configuration.processing_job_class
|
|
31
|
+
job_class = if job_class_or_module_name.respond_to?(:perform_later)
|
|
32
|
+
job_class_or_module_name
|
|
33
|
+
else
|
|
34
|
+
job_class_or_module_name.constantize
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
job_class.perform_later(webhook)
|
|
38
|
+
end
|
|
39
|
+
|
|
24
40
|
# This is the heart of your webhook processing. Override this method and define your processing inside of it.
|
|
25
41
|
# The `received_webhook` will provide access to the `ReceivedWebhook` model, which contains the received
|
|
26
42
|
# body of the webhook request, but also the full (as-full-as-possible) clone of the original ActionDispatch::Request
|
|
@@ -15,6 +15,11 @@ module Munster
|
|
|
15
15
|
s.permit_transition(:processing, :skipped)
|
|
16
16
|
s.permit_transition(:processing, :processed)
|
|
17
17
|
s.permit_transition(:processing, :error)
|
|
18
|
+
s.permit_transition(:error, :received)
|
|
19
|
+
|
|
20
|
+
s.after_committed_transition_to(:received) do |webhook|
|
|
21
|
+
webhook.handler.enqueue(webhook)
|
|
22
|
+
end
|
|
18
23
|
end
|
|
19
24
|
|
|
20
25
|
# Store the pertinent data from an ActionDispatch::Request into the webhook.
|
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
Munster.configure do |config|
|
|
2
2
|
# Active Handlers are defined as hash with key as a service_id and handler class that would handle webhook request.
|
|
3
|
+
# A Handler must respond to `.new` and return an object roughly matching `Munster::BaseHandler` in terms of interface.
|
|
4
|
+
# Use module names (strings) here to allow the handler modules to be lazy-loaded by Rails.
|
|
5
|
+
#
|
|
3
6
|
# Example:
|
|
4
|
-
# {:test => TestHandler, :inactive => InactiveHandler}
|
|
7
|
+
# {:test => "TestHandler", :inactive => "InactiveHandler"}
|
|
5
8
|
config.active_handlers = {}
|
|
6
9
|
|
|
7
|
-
# It's possible to overwrite default processing job to enahance it. As example if you want to add
|
|
10
|
+
# It's possible to overwrite default processing job to enahance it. As example if you want to add custom
|
|
11
|
+
# locking or retry mechanism. You want to inherit that job from Munster::ProcessingJob because the background
|
|
12
|
+
# job also manages the webhook state.
|
|
8
13
|
#
|
|
9
14
|
# Example:
|
|
10
15
|
#
|
|
@@ -15,9 +20,9 @@ Munster.configure do |config|
|
|
|
15
20
|
# end
|
|
16
21
|
# end
|
|
17
22
|
#
|
|
18
|
-
#
|
|
23
|
+
# In the config a string with your job' class name can be used so that the job can be lazy-loaded by Rails:
|
|
19
24
|
#
|
|
20
|
-
# config.processing_job_class = WebhookProcessingJob
|
|
25
|
+
# config.processing_job_class = "WebhookProcessingJob"
|
|
21
26
|
|
|
22
27
|
# We're using a common interface for error reporting provided by Rails, e.g Rails.error.report. In some cases
|
|
23
28
|
# you want to enhance those errors with additional context. As example to provide a namespace:
|
|
@@ -25,4 +30,11 @@ Munster.configure do |config|
|
|
|
25
30
|
# { appsignal: { namespace: "webhooks" } }
|
|
26
31
|
#
|
|
27
32
|
# config.error_context = { appsignal: { namespace: "webhooks" } }
|
|
33
|
+
|
|
34
|
+
# Incoming webhooks will be written into your DB without any prior validation. By default, Munster limits the
|
|
35
|
+
# request body size for webhooks to 512 KiB, so that it would not be too easy for an attacker to fill your
|
|
36
|
+
# database with junk. However, if you are receiving very large webhook payloads you might need to increase
|
|
37
|
+
# that limit (or make it even smaller for extra security)
|
|
38
|
+
#
|
|
39
|
+
# config.request_body_size_limit = 2.megabytes
|
|
28
40
|
end
|
data/lib/munster/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: munster
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.4.
|
|
4
|
+
version: 0.4.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Stanislav Katkov
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2024-07-
|
|
11
|
+
date: 2024-07-29 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: rails
|
|
@@ -170,6 +170,10 @@ files:
|
|
|
170
170
|
- example/tmp/.keep
|
|
171
171
|
- example/tmp/pids/.keep
|
|
172
172
|
- example/vendor/.keep
|
|
173
|
+
- handler-examples/customer_io_handler.rb
|
|
174
|
+
- handler-examples/revolut_business_v1_handler.rb
|
|
175
|
+
- handler-examples/revolut_business_v2_handler.rb
|
|
176
|
+
- handler-examples/starling_payments_handler.rb
|
|
173
177
|
- lib/munster.rb
|
|
174
178
|
- lib/munster/base_handler.rb
|
|
175
179
|
- lib/munster/controllers/receive_webhooks_controller.rb
|