bullet_train 1.24.0 → 1.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b29ed8e34efd6dd7f03bd1dd326fbe72c11f649ae444aca7d24ce569d5d6465
-  data.tar.gz: '0947600e8b283a1ec32336db44958a59252dbf2fc046e87cd52bde0ce39f7899'
+  metadata.gz: 551a29522ebbd3e77672eb47a987b2fdc3962ee45244cac05b8f8b1b4390d1d3
+  data.tar.gz: 6b21eaa284e4128d53703ab76257357bc75dbaa1a466e8282cb3fdeee244fafb
 SHA512:
-  metadata.gz: 3e582753d6f086561543c1c74349ddac280141a48003a458add58fa6567d3199ee381971cb63c35c7c289843fd52068c0d5a5dc921d16a8393eb781e45cebc96
-  data.tar.gz: '09ba7e11a89b2432a7e7cff7b2cad86381815d2e199c6b40934b4979a6641e67aeecdef7802662772f8334d0c5f0d2c88cd84c5ec94c0522a32103b38ff93341'
+  metadata.gz: 2576dfbdfe1a290ac469855878350f7f29042fda11866e21f1dfa5967f35f681ff533616757412dfa22bc7422a66610203de88e5f4bd0a1968da975fb7519b8a
+  data.tar.gz: ec63a264f9f2b4e56444215013b908c73c2327216a608929233e5c14b89d92c19d18557fb71d0431db2dbe83b43bbc2f395503c869bcdc5d0cb83bb0b9bb7450

data/docs/webhooks/incoming.md

@@ -5,3 +5,125 @@ Bullet Train makes it trivial to scaffold new endpoints where external systems c
 ```
 rails generate super_scaffold:incoming_webhooks
 ```
+
+## Security
+
+When receiving webhook events you need to ensure that they come from a trusted source. If the platform signs their webhook events, you can usually verify the event authenticity via their verification method. Bullet Train has webhook event signatures built in now. 
+
+### Managing the shared secret
+
+In order to verify signatures both sides need to have a shared secret. In the app that will be sending webhooks you'll set up an endpoint (via the UI or API) that points to the URL of the app that will be receiving them. After the endpoint is created you'll get a `webhook_secret` value. You should copy that value and set it as an `ENV` variable in the app that will be receiving the webhooks.
+
+For purposes of this example we'll assume that the shared secret is accessible to the receiving app as `ENV["BULLET_TRAIN_WEBHOOK_SECRET"]`.
+
+### Bullet Train apps receiving webhooks from another Bullet Train app
+
+In this case you can make direct use of the `BulletTrain::OutgoingWebhooks::Signature` class that comes with your Bullet Train installation.
+
+In the app that's going to be receiving the webhooks you'd do something like this:
+
+```
+rails generate super_scaffold:incoming_webhooks OtherBulletTrainApp
+```
+
+Then open `app/controllers/webhooks/incoming/other_bullet_train_app_webhooks_controller.rb` and add a `before_action :verify_authenticity` call that looks like this:
+
+```ruby
+before_action :verify_authenticity, only: [:create]
+
+def verify_authenticity
+  unless BulletTrain::OutgoingWebhooks::Signature.verify_request(request, ENV["BULLET_TRAIN_WEBHOOK_SECRET"])
+    # Respond with an error code and message that you usually have for non-existent endpoints.
+    render json: {error: "Not found"}, status: :not_found
+  end
+end
+```
+
+### Other Rails apps receiving webhooks from a Bullet Train app
+
+In this case you can use rails scaffolding to generate a route and controller for handling your webhook:
+
+```
+rails g controller BulletTrainWebhooks create
+```
+
+You'll also want to copy Bullet Train's `BulletTrain::OutgoingWebhooks::Signature` class into your project. (Here we should link to the actual implementation in the `core` repo so that we always point to the current implementation and not one that's frozen in time.)
+
+After adding `BulletTrain::OutgoingWebhooks::Signature` to your project you can edit `app/controllers/bullet_train_webhooks_controller.rb` to add a `before_action :verify_authenticity` call that looks like this:
+
+```ruby
+before_action :verify_authenticity, only: [:create]
+
+def verify_authenticity
+  unless BulletTrain::OutgoingWebhooks::Signature.verify_request(request, ENV["BULLET_TRAIN_WEBHOOK_SECRET"])
+    # Respond with an error code and message that you usually have for non-existent endpoints.`
+    render json: {error: "Not found"}, status: :not_found
+  end
+end
+```
+
+## Other apps receiving webhooks from a Bullet Train app
+
+Apps in other languages and frameworks will need to port the code from `bullet_train-core/bullet_train-outgoing_webhooks/lib/bullet_train/outgoing_webhooks/signature.rb` in this particular language/framework similarly to how it's described in the previous section for Rails apps. You would need to provide the verification code to your users or ask them to take the example of the `signature.rb` Ruby code. If you do so, please let us know so we can add more tried and tested examples here.
+
+## Other, less secure, ways to verify authenticity
+
+Sometimes, platforms that send outgoing webhook events don't have a signature verification mechanism. In this case, you can fall back to other less secure ways of verifying that it's not a random person sending something to your endpoint that is open to the Internet when you do:
+
+```
+rails generate super_scaffold: incoming_webhooks LessSecureApp
+```
+
+1. If you know the IP addresses the events will come from, you can check for them when receiving the events.
+2. Some platforms allow you to set custom headers. There you could set a secret `SecureRandom.hex` key, that you would verify when receiving the event.
+3. If you can't set custom headers, your endpoint will need to have a unique "key" in its path param or as a query param.
+
+Here are some examples of how you would implement those less secure options if you would not have the signature verification option.
+
+In the examples below, we will raise an error when there is an issue with the verification. This is for your error tracking. You will usually handle this error in the create action to return a message and status code that you would usually return for non-existent endpoints.
+
+### Verifying IP addresses
+
+Given an env var that you populated with the expected IPs `LESS_SECURE_APP_IP_ALLOWLIST=4.311.354.505,62.9.433.116`, you could write the following code in `app/controllers/webhooks/incoming/less_secure_app_webhooks_controller.rb`:
+
+```ruby
+before_action :verify_source_ip, only: [:create]
+
+def verify_source_ip
+  source_ip = request.remote_ip
+  allowlist = ENV["LESS_SECURE_APP_IP_ALLOWLIST"]&.split(",")&.map(&:strip) || []
+
+  if allowlist.empty?
+    raise UnverifiedDomainError, "Not ready to accept LessSecureApp webhooks because no LessSecureApp IP allowlist is configured."
+  end
+
+  unless allowlist.include?(source_ip)
+    raise UnverifiedDomainError, "Webhook request from unauthorized domain"
+  end
+
+  true
+end
+```
+
+### Verifying a secret
+
+You would first need to generate a secret. You could do so by using Ruby's `SecureRandom.hex` method. Then, store the value in an environment variable like `LESS_SECURE_APP_WEBHOOK_SECRET`. Now you could have an additional before action in the `app/controllers/webhooks/incoming/less_secure_app_webhooks_controller.rb`:
+
+```ruby
+before_action :verify_endpoint_secret_param, only: [:create]
+
+def verify_endpoint_secret_param
+  expected_secret = ENV["LESS_SECURE_APP_WEBHOOK_SECRET"]
+  provided_secret = params[:secret]
+
+  if expected_secret.blank?
+    raise InvalidSecretError, "Not ready to accept ClickFunnels webhooks because no endpoint secret is configured."
+  end
+
+  unless provided_secret.present? && ActiveSupport::SecurityUtils.secure_compare(provided_secret, expected_secret)
+    raise InvalidSecretError, "Invalid webhook secret"
+  end
+
+  true
+end
+```

data/docs/webhooks/outgoing.md

@@ -1,7 +1,7 @@
 # Outgoing Webhooks
 
 ## Introduction
-Webhooks allow for users to be notified via HTTP request when activity takes place on their team in your application. Bullet Train applications include an entire user-facing UI that allows them not only to subscribe to webhooks, but also see a history of their attempted deliveries and debug delivery issues.
+Webhooks allow for users to be notified via HTTP request when activity takes place on potentially any piece of data in your application. Bullet Train applications include an entire user-facing UI that allows them not only to create webhook endpoints, but also see a history of their attempted deliveries and debug delivery issues.
 
 ## Default Event Types
 Bullet Train can deliver webhooks for any model you've added under `Team`. We call the model a webhook is being issued for the "subject". 
@@ -27,6 +27,9 @@ payment.generate_webhook(:succeeded)
 ## Delivery
 Webhooks are delivered asyncronously in a background job by default. If the resulting HTTP request results in a status code other than those in the 2XX series, it will be considered a failed attempt and delivery will be reattempted a number of times.
 
+## Security
+Your outgoing webhook events come with a signature that your users can verify on the receiving end. More info in the [Security section of the Incoming Webhooks docs](./incoming.md#security)
+
 ## Future Plans
  - Allow users to filter webhooks to be generated by a given parent model. For example, they should be able to subscribe to `post.created`, but only for `Post` objects created within a certain `Project`.
  - Integrate [Hammerstone Refine](https://hammerstone.dev) to allow even greater configurability for filtering webhooks.

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.24.0"
+  VERSION = "1.25.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.24.0
+  version: 1.25.0
 platform: ruby
 authors:
 - Andrew Culver