mailtrap 2.11.0 → 2.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b63e81a019d2e0e7e4361de7ca3c511ffc3d0c292dc8db17c1866e986f57f18
-  data.tar.gz: 1b1efad54b339d0271d8c36970c1c668a345e31611a22cb3782ebc6556bd6543
+  metadata.gz: b6606da8d73e2112b813b87000d3aaa63c5490cf2d046dedf59eb5a4f56fc619
+  data.tar.gz: a7647dad5291d79758edd52e2b01c57e3e475d998a271ddcd5f6daf24455f59c
 SHA512:
-  metadata.gz: 8e03088d16735f15494b4eee20f6c58dd5a9ec0fb031836326b086687f5cc415d1c841744f27f6ca46c9203952d6abd989ed2f75c4b550fac53b58b62d314838
-  data.tar.gz: 63fc1ce090a0ee019693ed36794f5319f7b94caa29302ca9a2f7920b7db92dc611aeed74bd9ba0de4853e5626d108a520c11e0e1eb51dcf83418e1ff3b1105f7
+  metadata.gz: e8bca46ba63dfa33175e89b2fcdaba9cce1701d904b6eee25a4808e57524b17dd7f97f483e6289c889fdb6006d35ced29c857beacdc1d2431f8c43a26d878161
+  data.tar.gz: 7dbeaaf7198cc263e2ab8264113b0992836a2141745d96edd031f9ff33934649ab4b1cf5bf9a882016a63e243c77d129be61f8f9ab3957b8091019fdb90e2593

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [2.11.1] - 2026-07-02
+
+## What's Changed
+* Release v2.11.0 by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/109
+* MT-22022: Add webhook signature verification helper by @Rabsztok in https://github.com/mailtrap/mailtrap-ruby/pull/110
+* Add draft-release workflow placeholder by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/111
+* Implement draft-release workflow by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/112
+
+## New Contributors
+* @Rabsztok made their first contribution in https://github.com/mailtrap/mailtrap-ruby/pull/110
+
+**Full Changelog**: https://github.com/mailtrap/mailtrap-ruby/compare/v2.11.0...v2.11.1
+
 ## [2.11.0] - 2026-05-14
 ## What's Changed
 * Update sandboxes api by @IgorDobryn in https://github.com/mailtrap/mailtrap-ruby/pull/103

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mailtrap (2.11.0)
+    mailtrap (2.11.1)
       base64
 
 GEM

data/README.md

@@ -8,7 +8,6 @@
 
 This client uses API v2, for v1 refer to [this documentation](https://mailtrap.docs.apiary.io/)
 
-
 ## Prerequisites
 
 To get the most out of this official Mailtrap.io Ruby SDK:
@@ -176,7 +175,7 @@ Email API:
 
 - Full Email Sending – [`full.rb`](examples/full.rb)
 - Batch Sending – [`batch.rb`](examples/batch.rb)
-- Sending Domains API  – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
+- Sending Domains API – [`sending_domains_api.rb`](examples/sending_domains_api.rb)
 - Sending Stats API – [`stats_api.rb`](examples/stats_api.rb)
 - Email Logs API – [`email_logs_api.rb`](examples/email_logs_api.rb)
 - Webhooks API – [`webhooks_api.rb`](examples/webhooks_api.rb)
@@ -199,6 +198,7 @@ General:
 - Billing API – [`billing_api.rb`](examples/billing_api.rb)
 - Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
 - Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
+- Verifying webhook signatures – [`webhooks_signature_verification.ru`](examples/webhooks_signature_verification.ru)
 
 ## Migration guide v1 → v2
 
@@ -213,14 +213,14 @@ Bug reports and pull requests are welcome on [GitHub](https://github.com/railswa
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive 
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
 prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
 To release a new version, update the version number in `version.rb`, and then
 run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and the created tag, and push the `.gem` file to 
+push git commits and the created tag, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
 To run the documentation server, first generate the documentation with
@@ -241,4 +241,4 @@ Everyone interacting in the Mailtrap project's codebases, issue trackers, chat r
 
 ## Compatibility with previous releases
 
-Versions of this package up to 2.0.2 were an [unofficial client](https://github.com/vchin/mailtrap-client) developed by [@vchin](https://github.com/vchin). Package version 3 is a completely new package. 
+Versions of this package up to 2.0.2 were an [unofficial client](https://github.com/vchin/mailtrap-client) developed by [@vchin](https://github.com/vchin). Package version 3 is a completely new package.

data/lib/mailtrap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailtrap
-  VERSION = '2.11.0'
+  VERSION = '2.11.1'
 end

data/lib/mailtrap/webhooks.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Mailtrap
+  # Helpers for working with inbound Mailtrap webhooks.
+  #
+  # @see https://docs.mailtrap.io/email-api-smtp/advanced/webhooks#verifying-the-signature
+  module Webhooks
+    # Hex-encoded HMAC-SHA256 signature length.
+    SIGNATURE_HEX_LENGTH = 64
+
+    # Verifies the HMAC-SHA256 signature of a Mailtrap webhook payload.
+    #
+    # Mailtrap signs every outbound webhook by computing
+    # `HMAC-SHA256(signing_secret, raw_request_body)` and sending the lowercase
+    # hex digest in the `Mailtrap-Signature` HTTP header. Compute the same
+    # digest on your side and compare it in constant time.
+    #
+    # The comparison is performed with {OpenSSL.fixed_length_secure_compare} to
+    # avoid timing side-channels.
+    #
+    # The method never raises on inputs that could plausibly arrive over the
+    # wire (empty strings, wrong-length signatures, non-hex characters, missing
+    # secret) — it simply returns `false`. This makes it safe to call directly
+    # from a controller without rescuing.
+    #
+    # @param payload [String] The raw request body, exactly as received.
+    #   **Do not** parse and re-serialize the JSON — re-encoding may reorder
+    #   keys or alter whitespace and invalidate the signature.
+    # @param signature [String] The value of the `Mailtrap-Signature` HTTP
+    #   header (lowercase hex string).
+    # @param signing_secret [String] The webhook's `signing_secret`, returned
+    #   by {WebhooksAPI#create} on webhook creation.
+    # @return [Boolean] `true` if the signature is valid for the given payload
+    #   and secret, `false` otherwise.
+    def self.verify_signature(payload:, signature:, signing_secret:)
+      return false unless [payload, signature, signing_secret].all? { |v| v.is_a?(String) && !v.empty? }
+      return false if signature.bytesize != SIGNATURE_HEX_LENGTH
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', signing_secret, payload)
+
+      OpenSSL.fixed_length_secure_compare(expected, signature)
+    rescue ArgumentError
+      # fixed_length_secure_compare raises ArgumentError on length mismatch
+      false
+    end
+  end
+end

data/lib/mailtrap.rb

@@ -27,6 +27,7 @@ require_relative 'mailtrap/sandbox_messages_api'
 require_relative 'mailtrap/sandbox_attachments_api'
 require_relative 'mailtrap/stats_api'
 require_relative 'mailtrap/webhooks_api'
+require_relative 'mailtrap/webhooks'
 
 module Mailtrap
   # @!macro api_errors

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtrap
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.11.1
 platform: ruby
 authors:
 - Railsware Products Studio LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -104,6 +104,7 @@ files:
 - lib/mailtrap/suppressions_api.rb
 - lib/mailtrap/version.rb
 - lib/mailtrap/webhook.rb
+- lib/mailtrap/webhooks.rb
 - lib/mailtrap/webhooks_api.rb
 - mailtrap.gemspec
 homepage: https://github.com/mailtrap/mailtrap-ruby
@@ -129,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Official mailtrap.io API client