helo-email-sdk 1.0.0.pre.beta.2 → 1.0.0.pre.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 612d57ecd6a1b1917fe6d79997e1e444bee7b26d2d7dc851a7727509f4f29e67
-  data.tar.gz: 28bc563518998af787122744b916eab205993fff3d492ee00fd4b196e864f989
+  metadata.gz: cbf62a1f7adb7ad672a9ddf17441cc9cda10e7c199775a4bf3a94785e2f3ba3d
+  data.tar.gz: 434a84d00c0104fb81211d0c105293f2dc1271b59a8872003b761d151247249d
 SHA512:
-  metadata.gz: 0e7b810a2624aaec9cfcb9818b90bdcbf5771bd70f566aab9b29f7d36e811003cd28895038fce168d2e50ddc476032b52c70f01ea08aca31debce6963e3e8ac9
-  data.tar.gz: 847cf7cf9fe2e78f5d1ff75e246fbe68d88d1eab506b18588af26a1f00d490a866dd6f75dbb569dbd8251cce9c28a051197b1728ff941d4c36a4f53c39fbece4
+  metadata.gz: 5bd2ba8cd121447ead38cbd6916ccdbbd5c755afd4035d0c550fab2c82220ec2f56d80f2ebe5bc23a9352acd21bd7f2f68867a0c3feddfeca322071c51c8bb4a
+  data.tar.gz: 1f3bb34bbcfafc14d5d7d2ec10e9c74a9bc924db20b240e639d30f42423cd70e48f9e9fda9b0736ebc683061cbd9082faa681952131449e01645330e89b82b96

data/README.md

@@ -0,0 +1,125 @@
+# helo-email-sdk
+
+Helo API
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "helo-email-sdk"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Configure the SDK once, at boot:
+
+```ruby
+require "helo-email-sdk"
+
+Helo.configure do |config|
+  config.api_key = ENV.fetch("HELO_API_KEY")
+  config.base_url = "https://api.helohq.com" # optional, this is the default
+end
+```
+
+## Usage
+
+Each API is a class with class-level methods. Responses come back as model objects with
+typed attribute readers.
+
+```ruby
+result = Helo::Channels.list
+```
+
+Methods that take parameters accept a hash:
+
+```ruby
+result = Helo::Channels.list(limit: 10)
+```
+
+See the [API docs](#apis) for every method, with a runnable example each.
+
+### Errors
+
+Failed requests raise `Helo::APIError`:
+
+```ruby
+begin
+  Helo::Channels.list
+rescue Helo::APIError => e
+  e.code    # HTTP status
+  e.detail  # human-readable detail from the API
+  e.errors  # field-level validation errors, when present
+end
+```
+
+## Webhook signature verification
+
+Webhook deliveries are signed with the endpoint's signing key. Verify every delivery before
+acting on it, against the **raw** request body — parsing and re-serializing the JSON changes
+the bytes and the signature will not match.
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    Helo::WebhookSignatures.verify!(
+      request.headers["X-Helo-Webhook-Signature"],
+      request.raw_post, # raw body, exactly as received
+      ENV.fetch("HELO_WEBHOOK_SIGNING_KEY")
+    )
+
+    event = JSON.parse(request.raw_post)
+    # ... handle the event, then acknowledge quickly
+    head :no_content
+  rescue Helo::WebhookSignatures::Error
+    head :bad_request
+  end
+end
+```
+
+`verify!` returns `true` when the signature is valid and raises otherwise. Each rejection has
+its own class, so a stale delivery can be treated differently from a genuinely bad one:
+
+| Exception | Meaning |
+| --- | --- |
+| `MalformedHeaderError` | The header was not in the expected format |
+| `UnsupportedVersionError` | The delivery used a signing scheme this SDK version cannot verify — upgrade the gem |
+| `TimestampSkewError` | Correctly signed, but too old to accept — possible replay, or clock drift |
+| `SignatureMismatchError` | Wrong signing key, or the body was modified in transit |
+
+All four inherit from `Helo::WebhookSignatures::Error`, so `rescue` that one class
+to catch any rejection. If you only want a boolean, use `valid?` instead:
+
+```ruby
+if Helo::WebhookSignatures.valid?(signature_header, raw_body, signing_key)
+  # ...
+end
+```
+
+The signature header may carry several versions at once (`t=...,v1=...,v2=...`) while a new
+signing scheme is being rolled out. This SDK verifies against the newest version it supports
+(`SUPPORTED_VERSIONS`) and ignores elements it does not recognize, so a rollout will not break
+this integration.
+
+To compute a signature yourself — signing a fixture in tests, for example — use
+`Helo::WebhookSignatures.generate(payload, signing_key, timestamp)`.
+
+## APIs
+
+- [Helo::Channels](docs/Channels.md)
+- [Helo::Activity](docs/Activity.md)
+- [Helo::Domains](docs/Domains.md)
+- [Helo::Sending](docs/Sending.md)
+- [Helo::Broadcasts](docs/Broadcasts.md)
+- [Helo::Statistics](docs/Statistics.md)
+- [Helo::Suppressions](docs/Suppressions.md)
+- [Helo::Webhooks](docs/Webhooks.md)

data/lib/helo/apis/statistics.rb

@@ -4,19 +4,19 @@ module Helo
   class Statistics < API
     def retrieve_hourly(request_data = {})
       request = StatisticsRetrieveHourlyRequest.new(request_data)
-      response = @client.request(:get, "/activity/statistics/hourly", params: request.to_params)
+      response = @client.request(:get, "/statistics/hourly", params: request.to_params)
       StatisticsHourlyResponse.from_hash(response.body)
     end
 
     def retrieve_daily(request_data = {})
       request = StatisticsRetrieveDailyRequest.new(request_data)
-      response = @client.request(:get, "/activity/statistics/daily", params: request.to_params)
+      response = @client.request(:get, "/statistics/daily", params: request.to_params)
       StatisticsDailyResponse.from_hash(response.body)
     end
 
     def retrieve_totals(request_data = {})
       request = StatisticsRetrieveTotalsRequest.new(request_data)
-      response = @client.request(:get, "/activity/statistics/totals", params: request.to_params)
+      response = @client.request(:get, "/statistics/totals", params: request.to_params)
       StatisticsTotalsResponse.from_hash(response.body)
     end
 

data/lib/helo/core/client.rb

@@ -10,15 +10,6 @@ module Helo::Core
       raise ArgumentError, "base_url is not configured" if configuration.base_url.to_s.empty?
 
       @configuration = configuration
-      @connection = Faraday.new(url: configuration.base_url) do |f|
-        f.request :json
-        f.response :json
-        f.adapter Faraday.default_adapter
-        f.options.params_encoder = Faraday::FlatParamsEncoder
-
-        # Allow custom Faraday configuration
-        configuration.faraday_configuration_block&.call(f)
-      end
     end
 
     def request(method, path, params: {}, body: nil, headers: {})
@@ -43,7 +34,17 @@ module Helo::Core
 
     private
 
-    attr_reader :connection
+    def connection
+      @_connection ||= Faraday.new(url: configuration.base_url) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+        f.options.params_encoder = Faraday::FlatParamsEncoder
+
+        # Allow custom Faraday configuration
+        configuration.faraday_configuration_block&.call(f)
+      end
+    end
 
     def current_api_key
       token = configuration.api_key

data/lib/helo/enums/webhook_event.rb

@@ -11,9 +11,13 @@ module Helo
     COMPLAINED = "complained"
     UNSUBSCRIBED = "unsubscribed"
     RESUBSCRIBED = "resubscribed"
+    DOMAIN_KEY_VERIFIED = "domain-key-verified"
+    DOMAIN_KEY_VERIFICATION_FAILED = "domain-key-verification-failed"
+    RETURN_PATH_DOMAIN_VERIFIED = "return-path-domain-verified"
+    RETURN_PATH_DOMAIN_VERIFICATION_FAILED = "return-path-domain-verification-failed"
 
     def self.all
-      [ACCEPTED, PROCESSED, BOUNCED, DELIVERED, OPENED, CLICKED, COMPLAINED, UNSUBSCRIBED, RESUBSCRIBED].freeze
+      [ACCEPTED, PROCESSED, BOUNCED, DELIVERED, OPENED, CLICKED, COMPLAINED, UNSUBSCRIBED, RESUBSCRIBED, DOMAIN_KEY_VERIFIED, DOMAIN_KEY_VERIFICATION_FAILED, RETURN_PATH_DOMAIN_VERIFIED, RETURN_PATH_DOMAIN_VERIFICATION_FAILED].freeze
     end
   end
 end

data/lib/helo/models/accepted_webhook_payload.rb

@@ -6,12 +6,12 @@ module Helo
 
     api_attribute :event_type, :string, key: "eventType"
     api_attribute :recipients, key: "recipients"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/bounced_details.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Helo
+  class BouncedDetails
+    include Helo::Core::Model
+
+    api_attribute :type, :string, key: "type"
+    api_attribute :sub_type, :string, key: "subType"
+    api_attribute :code, :string, key: "code"
+  end
+end

data/lib/helo/models/bounced_webhook_payload.rb

@@ -5,14 +5,14 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::BouncedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/clicked_details.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Helo
+  class ClickedDetails
+    include Helo::Core::Model
+
+    api_attribute :link, :string, key: "link"
+    api_attribute :ip, :string, key: "ip"
+    api_attribute :country, :string, key: "country"
+    api_attribute :country_code, :string, key: "countryCode"
+    api_attribute :client, Helo::Core::ModelType.new("Helo::ClientDetails"), key: "client"
+    api_attribute :device, Helo::Core::ModelType.new("Helo::DeviceDetails"), key: "device"
+  end
+end

data/lib/helo/models/clicked_webhook_payload.rb

@@ -5,14 +5,14 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::ClickedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/client_details.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Helo
+  class ClientDetails
+    include Helo::Core::Model
+
+    api_attribute :family, :string, key: "family"
+    api_attribute :version, :string, key: "version"
+  end
+end

data/lib/helo/models/complained_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class ComplainedDetails
+    include Helo::Core::Model
+
+    api_attribute :type, :string, key: "type"
+  end
+end

data/lib/helo/models/complained_webhook_payload.rb

@@ -5,14 +5,14 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::ComplainedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/delivered_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class DeliveredDetails
+    include Helo::Core::Model
+
+    api_attribute :response, :string, key: "response"
+  end
+end

data/lib/helo/models/delivered_webhook_payload.rb

@@ -5,14 +5,14 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::DeliveredDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/delivery_webhook_payload_common.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Helo
+  class DeliveryWebhookPayloadCommon
+    include Helo::Core::Model
+
+    api_attribute :message_id, :string, key: "messageId"
+    api_attribute :channel_id, :string, key: "channelId"
+    api_attribute :mail_type, :string, key: "mailType"
+    api_attribute :subject, :string, key: "subject"
+    api_attribute :tags, key: "tags"
+    api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
+  end
+end

data/lib/helo/models/device_details.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Helo
+  class DeviceDetails
+    include Helo::Core::Model
+
+    api_attribute :brand, :string, key: "brand"
+    api_attribute :family, :string, key: "family"
+    api_attribute :model, :string, key: "model"
+  end
+end

data/lib/helo/models/domain_key_verification_failed_payload.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class DomainKeyVerificationFailedPayload
+    include Helo::Core::Model
+
+    api_attribute :event_type, :string, key: "eventType"
+    api_attribute :domain_id, :string, key: "domainId"
+    api_attribute :domain_name, :string, key: "domainName"
+    api_attribute :dns_record_host, :string, key: "dnsRecordHost"
+    api_attribute :timestamp, :datetime, key: "timestamp"
+  end
+end

data/lib/helo/models/domain_key_verified_payload.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class DomainKeyVerifiedPayload
+    include Helo::Core::Model
+
+    api_attribute :event_type, :string, key: "eventType"
+    api_attribute :domain_id, :string, key: "domainId"
+    api_attribute :domain_name, :string, key: "domainName"
+    api_attribute :dns_record_host, :string, key: "dnsRecordHost"
+    api_attribute :timestamp, :datetime, key: "timestamp"
+  end
+end

data/lib/helo/models/domain_payload_common.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Helo
+  class DomainPayloadCommon
+    include Helo::Core::Model
+
+    api_attribute :domain_id, :string, key: "domainId"
+    api_attribute :domain_name, :string, key: "domainName"
+    api_attribute :dns_record_host, :string, key: "dnsRecordHost"
+    api_attribute :timestamp, :datetime, key: "timestamp"
+  end
+end

data/lib/helo/models/engagement_details.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class EngagementDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+    api_attribute :country, :string, key: "country"
+    api_attribute :country_code, :string, key: "countryCode"
+    api_attribute :client, Helo::Core::ModelType.new("Helo::ClientDetails"), key: "client"
+    api_attribute :device, Helo::Core::ModelType.new("Helo::DeviceDetails"), key: "device"
+  end
+end

data/lib/helo/models/message.rb

@@ -13,5 +13,7 @@ module Helo
     api_attribute :status, :string, key: "status"
     api_attribute :subject, :string, key: "subject"
     api_attribute :recipients, key: "recipients"
+    api_attribute :tags, key: "tags"
+    api_attribute :statistics, Helo::Core::ModelType.new("Helo::MessageStatistics"), key: "statistics"
   end
 end

data/lib/helo/models/message_details_response.rb

@@ -26,5 +26,6 @@ module Helo
     api_attribute :attachments, Helo::Core::ArrayType.new("Helo::MessageDetailsResponseAttachment"), key: "attachments"
     api_attribute :tracking, Helo::Core::ModelType.new("Helo::MessageDetailsResponseTracking"), key: "tracking"
     api_attribute :events, Helo::Core::ArrayType.new("Helo::MessageDetailsResponseEvent"), key: "events"
+    api_attribute :statistics, Helo::Core::ModelType.new("Helo::MessageStatistics"), key: "statistics"
   end
 end

data/lib/helo/models/message_statistics.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Helo
+  class MessageStatistics
+    include Helo::Core::Model
+
+    api_attribute :delivered, :integer, key: "delivered"
+    api_attribute :bounced, :integer, key: "bounced"
+    api_attribute :opened, :integer, key: "opened"
+    api_attribute :clicked, :integer, key: "clicked"
+    api_attribute :complained, :integer, key: "complained"
+    api_attribute :unsubscribed, :integer, key: "unsubscribed"
+  end
+end

data/lib/helo/models/opened_details.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class OpenedDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+    api_attribute :country, :string, key: "country"
+    api_attribute :country_code, :string, key: "countryCode"
+    api_attribute :client, Helo::Core::ModelType.new("Helo::ClientDetails"), key: "client"
+    api_attribute :device, Helo::Core::ModelType.new("Helo::DeviceDetails"), key: "device"
+  end
+end

data/lib/helo/models/opened_webhook_payload.rb

@@ -5,14 +5,14 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::OpenedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/processed_webhook_payload.rb

@@ -6,12 +6,12 @@ module Helo
 
     api_attribute :event_type, :string, key: "eventType"
     api_attribute :recipients, key: "recipients"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/recipient_event_fields.rb

@@ -5,6 +5,5 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
   end
 end

data/lib/helo/models/resubscribed_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class ResubscribedDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+  end
+end

data/lib/helo/models/resubscribed_webhook_payload.rb

@@ -5,14 +5,14 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::ResubscribedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/return_path_domain_verification_failed_payload.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class ReturnPathDomainVerificationFailedPayload
+    include Helo::Core::Model
+
+    api_attribute :event_type, :string, key: "eventType"
+    api_attribute :domain_id, :string, key: "domainId"
+    api_attribute :domain_name, :string, key: "domainName"
+    api_attribute :dns_record_host, :string, key: "dnsRecordHost"
+    api_attribute :timestamp, :datetime, key: "timestamp"
+  end
+end

data/lib/helo/models/return_path_domain_verified_payload.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  class ReturnPathDomainVerifiedPayload
+    include Helo::Core::Model
+
+    api_attribute :event_type, :string, key: "eventType"
+    api_attribute :domain_id, :string, key: "domainId"
+    api_attribute :domain_name, :string, key: "domainName"
+    api_attribute :dns_record_host, :string, key: "dnsRecordHost"
+    api_attribute :timestamp, :datetime, key: "timestamp"
+  end
+end

data/lib/helo/models/unsubscribed_details.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class UnsubscribedDetails
+    include Helo::Core::Model
+
+    api_attribute :ip, :string, key: "ip"
+  end
+end

data/lib/helo/models/unsubscribed_webhook_payload.rb

@@ -5,14 +5,14 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :event_type, :string, key: "eventType"
+    api_attribute :details, Helo::Core::ModelType.new("Helo::UnsubscribedDetails"), key: "details"
     api_attribute :recipient, :string, key: "recipient"
-    api_attribute :details, :string, key: "details"
-    api_attribute :timestamp, :datetime, key: "timestamp"
     api_attribute :message_id, :string, key: "messageId"
     api_attribute :channel_id, :string, key: "channelId"
     api_attribute :mail_type, :string, key: "mailType"
     api_attribute :subject, :string, key: "subject"
     api_attribute :tags, key: "tags"
     api_attribute :metadata, key: "metadata"
+    api_attribute :timestamp, :datetime, key: "timestamp"
   end
 end

data/lib/helo/models/webhook_payload_common.rb

@@ -5,11 +5,5 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :timestamp, :datetime, key: "timestamp"
-    api_attribute :message_id, :string, key: "messageId"
-    api_attribute :channel_id, :string, key: "channelId"
-    api_attribute :mail_type, :string, key: "mailType"
-    api_attribute :subject, :string, key: "subject"
-    api_attribute :tags, key: "tags"
-    api_attribute :metadata, key: "metadata"
   end
 end

data/lib/helo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Helo
-  VERSION = "1.0.0-beta.2"
+  VERSION = "1.0.0-beta.7"
 end

data/lib/helo/webhook_signatures.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Helo
+  # Helpers for verifying the signature on an incoming webhook request.
+  module WebhookSignatures
+    # Base class for every rejection reason, so callers that do not care why a
+    # webhook was rejected can rescue this one class.
+    class Error < StandardError; end
+
+    # The header was not in the documented
+    # t={timestamp},v{version}={signature} form.
+    class MalformedHeaderError < Error; end
+
+    # The header carried only signing schemes this SDK does not know how to
+    # verify. Upgrading the SDK is the fix; see SUPPORTED_VERSIONS.
+    class UnsupportedVersionError < Error; end
+
+    # The signature was correctly formed but its timestamp is too far from the
+    # current time, so it may be a replay.
+    class TimestampSkewError < Error; end
+
+    # The signature did not match the body, either because the body was tampered
+    # with or the signing key is wrong.
+    class SignatureMismatchError < Error; end
+
+    # Signing schemes this SDK can verify. The signature header may carry several
+    # versions at once (t=...,v1=...,v2=...) so that a new scheme can be rolled
+    # out while receivers upgrade; verification uses the newest version present
+    # that appears in this list, and ignores the rest.
+    SUPPORTED_VERSIONS = [1].freeze
+
+    TIMESTAMP_VALUE_REGEX = /\A\d+\z/
+    SIGNATURE_KEY_REGEX = /\Av(\d+)\z/
+    HEX_SIGNATURE_REGEX = /\A[a-f0-9]+\z/
+    MAX_TIMESTAMP_SKEW_SECONDS = 300 # 5 minutes
+
+    class << self
+      # Verify a webhook signature header against the raw request body.
+      #
+      # @param signature_header [String] value of the signature header sent with the webhook
+      # @param request_body [String] raw (unparsed) request body
+      # @param signing_key [String] signing key for the webhook endpoint
+      # @return [true] when the signature is valid
+      # @raise [Error] a subclass describing why the signature was rejected
+      def verify!(signature_header, request_body, signing_key)
+        timestamp, signatures = parse_header(signature_header)
+
+        version = newest_supported_version(signatures)
+        unless version
+          raise UnsupportedVersionError,
+                "Unsupported webhook signature version: header carries only " \
+                "#{signatures.keys.sort.map { |v| "v#{v}" }.join(', ')}"
+        end
+
+        skew = (Time.now.to_i - timestamp.to_i).abs
+        if skew > MAX_TIMESTAMP_SKEW_SECONDS
+          raise TimestampSkewError,
+                "Webhook signature timestamp outside tolerance: off by #{skew}s, " \
+                "tolerance is #{MAX_TIMESTAMP_SKEW_SECONDS}s"
+        end
+
+        computed = signature_for_version(version, request_body, signing_key, timestamp)
+        unless signatures.fetch(version).any? { |signature| secure_compare(computed, signature) }
+          raise SignatureMismatchError, "Webhook signature mismatch"
+        end
+
+        true
+      end
+
+      # Verify a webhook signature header, returning false instead of raising.
+      #
+      # @see #verify!
+      # @return [Boolean]
+      def valid?(signature_header, request_body, signing_key)
+        verify!(signature_header, request_body, signing_key)
+      rescue Error
+        false
+      end
+
+      # Compute the hex-encoded HMAC-SHA256 signature for a webhook payload,
+      # using the v1 signing scheme.
+      #
+      # @param payload [String] raw (unparsed) request body
+      # @param key [String] signing key for the webhook endpoint
+      # @param timestamp [String] unix timestamp in seconds, as sent in the signature header
+      # @return [String]
+      def generate(payload, key, timestamp)
+        OpenSSL::HMAC.hexdigest("SHA256", key, "#{timestamp}.#{payload}")
+      end
+
+      private
+
+      # Compute the signature for one signing scheme. This is the single place a
+      # new scheme needs to be added.
+      def signature_for_version(version, payload, key, timestamp)
+        case version
+        when 1 then generate(payload, key, timestamp)
+        end
+      end
+
+      # Split the header into its timestamp and its signatures keyed by version.
+      # Elements that are not recognized are ignored, so that a sender adding new
+      # elements does not break verification here.
+      def parse_header(signature_header)
+        timestamp = nil
+        signatures = Hash.new { |hash, key| hash[key] = [] }
+
+        signature_header.to_s.split(",").each do |element|
+          key, value = element.strip.split("=", 2)
+          next if value.nil?
+
+          if key == "t"
+            raise MalformedHeaderError, "Malformed webhook signature header" unless TIMESTAMP_VALUE_REGEX.match?(value)
+
+            timestamp = value
+            next
+          end
+
+          match = SIGNATURE_KEY_REGEX.match(key)
+          next unless match
+
+          version = match[1].to_i
+
+          # Only versions this SDK verifies have a signature format it can insist
+          # on; anything else is recorded but left unchecked.
+          if SUPPORTED_VERSIONS.include?(version) && !HEX_SIGNATURE_REGEX.match?(value)
+            raise MalformedHeaderError, "Malformed webhook signature header"
+          end
+
+          signatures[version] << value
+        end
+
+        if timestamp.nil? || signatures.empty?
+          raise MalformedHeaderError, "Malformed webhook signature header"
+        end
+
+        [timestamp, signatures]
+      end
+
+      # Pick the highest version present that this SDK can verify, so that once a
+      # sender emits a newer scheme the older one stops being honored here.
+      def newest_supported_version(signatures)
+        (signatures.keys & SUPPORTED_VERSIONS).max
+      end
+
+      def secure_compare(computed, given)
+        return false unless computed.bytesize == given.bytesize
+
+        OpenSSL.fixed_length_secure_compare(computed, given)
+      end
+    end
+  end
+end

data/lib/helo.rb

@@ -17,6 +17,7 @@ require_relative "helo/version"
 require_relative "helo/api_error"
 require_relative "helo/configuration"
 require_relative "helo/client"
+require_relative "helo/webhook_signatures"
 
 
 module Helo

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: helo-email-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.beta.2
+  version: 1.0.0.pre.beta.7
 platform: ruby
 authors:
 - Helo Email
@@ -86,6 +86,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/helo-email-sdk.rb
 - lib/helo.rb
 - lib/helo/api_error.rb
@@ -121,6 +122,7 @@ files:
 - lib/helo/models/activity_list_messages_request.rb
 - lib/helo/models/activity_mail_address.rb
 - lib/helo/models/attachment.rb
+- lib/helo/models/bounced_details.rb
 - lib/helo/models/bounced_webhook_payload.rb
 - lib/helo/models/broadcast_content.rb
 - lib/helo/models/broadcast_content_attachment.rb
@@ -137,7 +139,10 @@ files:
 - lib/helo/models/channel_details_response.rb
 - lib/helo/models/channel_tracking.rb
 - lib/helo/models/channels_list_request.rb
+- lib/helo/models/clicked_details.rb
 - lib/helo/models/clicked_webhook_payload.rb
+- lib/helo/models/client_details.rb
+- lib/helo/models/complained_details.rb
 - lib/helo/models/complained_webhook_payload.rb
 - lib/helo/models/create_channel_request.rb
 - lib/helo/models/create_channel_tracking.rb
@@ -145,14 +150,21 @@ files:
 - lib/helo/models/create_suppressions_request.rb
 - lib/helo/models/create_suppressions_response.rb
 - lib/helo/models/create_webhook_request.rb
+- lib/helo/models/delivered_details.rb
 - lib/helo/models/delivered_webhook_payload.rb
 - lib/helo/models/delivery_stats.rb
+- lib/helo/models/delivery_webhook_payload_common.rb
+- lib/helo/models/device_details.rb
 - lib/helo/models/dns_record_response.rb
 - lib/helo/models/dns_records_response.rb
 - lib/helo/models/domain_channel_response.rb
+- lib/helo/models/domain_key_verification_failed_payload.rb
+- lib/helo/models/domain_key_verified_payload.rb
+- lib/helo/models/domain_payload_common.rb
 - lib/helo/models/domain_response.rb
 - lib/helo/models/domain_with_dns_response.rb
 - lib/helo/models/domains_list_request.rb
+- lib/helo/models/engagement_details.rb
 - lib/helo/models/error_response.rb
 - lib/helo/models/mail_address.rb
 - lib/helo/models/message.rb
@@ -160,6 +172,8 @@ files:
 - lib/helo/models/message_details_response_attachment.rb
 - lib/helo/models/message_details_response_event.rb
 - lib/helo/models/message_details_response_tracking.rb
+- lib/helo/models/message_statistics.rb
+- lib/helo/models/opened_details.rb
 - lib/helo/models/opened_webhook_payload.rb
 - lib/helo/models/paginated_events_response.rb
 - lib/helo/models/paginated_messages_response.rb
@@ -176,7 +190,10 @@ files:
 - lib/helo/models/remove_suppression_result.rb
 - lib/helo/models/remove_suppressions_request.rb
 - lib/helo/models/remove_suppressions_response.rb
+- lib/helo/models/resubscribed_details.rb
 - lib/helo/models/resubscribed_webhook_payload.rb
+- lib/helo/models/return_path_domain_verification_failed_payload.rb
+- lib/helo/models/return_path_domain_verified_payload.rb
 - lib/helo/models/send_broadcast_request.rb
 - lib/helo/models/send_broadcast_request_message.rb
 - lib/helo/models/send_broadcast_request_template.rb
@@ -201,6 +218,7 @@ files:
 - lib/helo/models/suppression_response.rb
 - lib/helo/models/suppression_result.rb
 - lib/helo/models/suppressions_list_request.rb
+- lib/helo/models/unsubscribed_details.rb
 - lib/helo/models/unsubscribed_webhook_payload.rb
 - lib/helo/models/update_channel_request.rb
 - lib/helo/models/update_channel_tracking.rb
@@ -213,6 +231,7 @@ files:
 - lib/helo/models/webhook_response.rb
 - lib/helo/models/webhooks_list_request.rb
 - lib/helo/version.rb
+- lib/helo/webhook_signatures.rb
 homepage: https://rubygems.org/gems/helo-email-sdk
 licenses:
 - MIT