sendio 1.0.0

data/lib/sendio/webhooks.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Sendio
+  # The Webhooks module provides methods for managing webhooks via the send.io API.
+  # Webhooks allow you to receive real-time notifications about email events.
+  #
+  # Default tolerance for timestamp validation (5 minutes)
+  WEBHOOK_TOLERANCE_SECONDS = 300
+  #
+  # @example Create a webhook
+  #   Sendio::Webhooks.create(
+  #     endpoint: "https://webhook.example.com/handler",
+  #     events: ["email.sent", "email.delivered", "email.bounced"]
+  #   )
+  #
+  # @example List all webhooks
+  #   Sendio::Webhooks.list
+  #
+  # @example Retrieve a specific webhook
+  #   Sendio::Webhooks.get("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+  #
+  # @example Update a webhook
+  #   Sendio::Webhooks.update(
+  #     webhook_id: "430eed87-632a-4ea6-90db-0aace67ec228",
+  #     endpoint: "https://new-webhook.example.com/handler",
+  #     events: ["email.sent", "email.delivered"],
+  #     status: "enabled"
+  #   )
+  #
+  # @example Delete a webhook
+  #   Sendio::Webhooks.remove("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+  module Webhooks
+    class << self
+      # Create a new webhook to receive real-time notifications about email events
+      #
+      # @param params [Hash] The webhook parameters
+      # @option params [String] :endpoint The URL where webhook events will be sent (required)
+      # @option params [Array<String>] :events Array of event types to subscribe to (required)
+      #
+      # @return [Hash] The webhook object containing id, object type, and signing_secret
+      #
+      # @example
+      #   Sendio::Webhooks.create(
+      #     endpoint: "https://webhook.example.com/handler",
+      #     events: ["email.sent", "email.delivered", "email.bounced"]
+      #   )
+      def create(params = {})
+        path = "webhooks"
+        Sendio::Request.new(path, params, "post").perform
+      end
+
+      # Retrieve a list of webhooks for the authenticated user
+      #
+      # @param params [Hash] The pagination parameters
+      # @option params [Integer] :limit Number of webhooks to retrieve (max: 100, min: 1)
+      # @option params [String] :after The ID after which to retrieve more webhooks (for pagination)
+      # @option params [String] :before The ID before which to retrieve more webhooks (for pagination)
+      #
+      # @return [Hash] A paginated list of webhook objects
+      #
+      # @example
+      #   Sendio::Webhooks.list
+      #
+      # @example With pagination
+      #   Sendio::Webhooks.list(limit: 20, after: "4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      def list(params = {})
+        path = Sendio::PaginationHelper.build_paginated_path("webhooks", params)
+        Sendio::Request.new(path, {}, "get").perform
+      end
+
+      # Retrieve a single webhook for the authenticated user
+      #
+      # @param webhook_id [String] The webhook ID
+      #
+      # @return [Hash] The webhook object with full details
+      #
+      # @example
+      #   Sendio::Webhooks.get("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      def get(webhook_id = "")
+        path = "webhooks/#{webhook_id}"
+        Sendio::Request.new(path, {}, "get").perform
+      end
+
+      # Retrieve webhook events
+      #
+      # @param webhook_id [String] The webhook ID
+      # @param params [Hash] The pagination parameters
+      # @option params [Integer] :limit Number of webhook events to retrieve (max: 100, min: 1)
+      # @option params [String] :after The ID after which to retrieve more webhook events
+      #
+      # @return [Hash] A paginated list of webhook events
+      #
+      # @example
+      #   Sendio::Webhooks.list_events("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      #
+      # @example With pagination
+      #   Sendio::Webhooks.list_events("4dd369bc-aa82-4ff3-97de-514ae3000ee0", limit: 20, after: "msg_123")
+      def list_events(webhook_id, params = {})
+        path = Sendio::PaginationHelper.build_paginated_path("webhooks/#{webhook_id}/events", params)
+        Sendio::Request.new(path, {}, "get").perform
+      end
+
+      # Retrieve a webhook event
+      #
+      # @param webhook_id [String] The webhook ID
+      # @param event_id [String] The webhook event ID
+      #
+      # @return [Hash] The webhook event with full details
+      #
+      # @example
+      #   Sendio::Webhooks.get_event("4dd369bc-aa82-4ff3-97de-514ae3000ee0", "msg_123")
+      def get_event(webhook_id, event_id)
+        path = "webhooks/#{webhook_id}/events/#{event_id}"
+        Sendio::Request.new(path, {}, "get").perform
+      end
+
+      # Replay a webhook event
+      #
+      # Queues one more delivery of the event to the webhook. Manual replays do not schedule automatic retries.
+      #
+      # @param webhook_id [String] The webhook ID
+      # @param event_id [String] The webhook event ID
+      #
+      # @return [Hash] The replayed webhook event id and object type
+      #
+      # @example
+      #   Sendio::Webhooks.replay_event("4dd369bc-aa82-4ff3-97de-514ae3000ee0", "msg_123")
+      def replay_event(webhook_id, event_id)
+        path = "webhooks/#{webhook_id}/events/#{event_id}/replay"
+        Sendio::Request.new(path, {}, "post").perform
+      end
+
+      # Retrieve delivery attempts for a webhook event
+      #
+      # @param webhook_id [String] The webhook ID
+      # @param event_id [String] The webhook event ID
+      # @param params [Hash] The pagination parameters
+      # @option params [Integer] :limit Number of delivery attempts to retrieve (max: 100, min: 1)
+      # @option params [String] :after The ID after which to retrieve more delivery attempts
+      #
+      # @return [Hash] A paginated list of webhook event delivery attempts
+      #
+      # @example
+      #   Sendio::Webhooks.list_event_attempts("4dd369bc-aa82-4ff3-97de-514ae3000ee0", "msg_123")
+      #
+      # @example With pagination
+      #   Sendio::Webhooks.list_event_attempts(
+      #     "4dd369bc-aa82-4ff3-97de-514ae3000ee0",
+      #     "msg_123",
+      #     limit: 20,
+      #     after: "atmpt_123"
+      #   )
+      def list_event_attempts(webhook_id, event_id, params = {})
+        base_path = "webhooks/#{webhook_id}/events/#{event_id}/attempts"
+        path = Sendio::PaginationHelper.build_paginated_path(base_path, params)
+        Sendio::Request.new(path, {}, "get").perform
+      end
+
+      # Update an existing webhook configuration
+      #
+      # @param params [Hash] The webhook update parameters
+      # @option params [String] :webhook_id The webhook ID (required)
+      # @option params [String] :endpoint The URL where webhook events will be sent
+      # @option params [Array<String>] :events Array of event types to subscribe to
+      # @option params [String] :status The webhook status ("enabled" or "disabled")
+      #
+      # @return [Hash] The updated webhook object
+      #
+      # @example
+      #   Sendio::Webhooks.update(
+      #     webhook_id: "430eed87-632a-4ea6-90db-0aace67ec228",
+      #     endpoint: "https://new-webhook.example.com/handler",
+      #     events: ["email.sent", "email.delivered"],
+      #     status: "enabled"
+      #   )
+      def update(params = {})
+        webhook_id = params.delete(:webhook_id)
+        path = "webhooks/#{webhook_id}"
+        Sendio::Request.new(path, params, "patch").perform
+      end
+
+      # Rotate the signing secret of a webhook
+      #
+      # Generates a new signing secret for the webhook. The previous secret keeps working for 24 hours.
+      #
+      # @param webhook_id [String] The webhook ID
+      #
+      # @return [Hash] The webhook object containing id, object type, and the new signing_secret
+      #
+      # @example
+      #   Sendio::Webhooks.rotate_signing_secret("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      def rotate_signing_secret(webhook_id)
+        path = "webhooks/#{webhook_id}/signing-secret/rotate"
+        Sendio::Request.new(path, {}, "post").perform
+      end
+
+      # Remove an existing webhook
+      #
+      # @param webhook_id [String] The webhook ID
+      #
+      # @return [Hash] Confirmation object with id, object type, and deleted status
+      #
+      # @example
+      #   Sendio::Webhooks.remove("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      def remove(webhook_id = "")
+        path = "webhooks/#{webhook_id}"
+        Sendio::Request.new(path, {}, "delete").perform
+      end
+
+      # Verify a webhook payload using HMAC-SHA256 signature validation
+      # This validates that the webhook request came from Sendio and hasn't been tampered with
+      #
+      # @param params [Hash] The webhook verification parameters
+      # @option params [String] :payload The raw webhook payload body (required)
+      # @option params [Hash] :headers The webhook headers containing svix-id, svix-timestamp,
+      #   and svix-signature (required)
+      # @option params [String] :webhook_secret The signing secret from webhook creation (required)
+      #
+      # @return [Boolean] true if verification succeeds
+      # @raise [StandardError] If verification fails or required parameters are missing
+      #
+      # @example
+      #   Sendio::Webhooks.verify(
+      #     payload: request.body.read,
+      #     headers: {
+      #       svix_id: "id_1234567890abcdefghijklmnopqrstuvwxyz",
+      #       svix_timestamp: "1616161616",
+      #       svix_signature: "v1,signature_here"
+      #     },
+      #     webhook_secret: "whsec_1234567890abcdez"
+      #   )
+      def verify(params = {})
+        payload = params[:payload]
+        headers = params[:headers] || {}
+        webhook_secret = params[:webhook_secret]
+
+        validate_required_params(payload, headers, webhook_secret)
+        validate_timestamp(headers[:svix_timestamp])
+
+        signed_content = "#{headers[:svix_id]}.#{headers[:svix_timestamp]}.#{payload}"
+        decoded_secret = decode_secret(webhook_secret)
+        expected_signature = generate_signature(decoded_secret, signed_content)
+
+        verify_signature(headers[:svix_signature], expected_signature)
+      end
+
+      private
+
+      # Validate required parameters
+      def validate_required_params(payload, headers, webhook_secret)
+        validate_payload(payload)
+        validate_webhook_secret(webhook_secret)
+        validate_headers(headers)
+      end
+
+      # Validate payload is present
+      def validate_payload(payload)
+        raise "payload cannot be empty" if payload.nil? || payload.empty?
+      end
+
+      # Validate webhook secret is present
+      def validate_webhook_secret(webhook_secret)
+        raise "webhook_secret cannot be empty" if webhook_secret.nil? || webhook_secret.empty?
+      end
+
+      # Validate required headers are present
+      def validate_headers(headers)
+        raise "svix-id header is required" if headers[:svix_id].nil? || headers[:svix_id].empty?
+        raise "svix-timestamp header is required" if headers[:svix_timestamp].nil? || headers[:svix_timestamp].empty?
+        raise "svix-signature header is required" if headers[:svix_signature].nil? || headers[:svix_signature].empty?
+      end
+
+      # Validate timestamp to prevent replay attacks
+      def validate_timestamp(timestamp_header)
+        timestamp = timestamp_header.to_i
+        now = Time.now.to_i
+        diff = now - timestamp
+
+        return unless diff > WEBHOOK_TOLERANCE_SECONDS || diff < -WEBHOOK_TOLERANCE_SECONDS
+
+        raise "Timestamp outside tolerance window: difference of #{diff} seconds"
+      end
+
+      # Decode the signing secret (strip whsec_ prefix and base64 decode)
+      def decode_secret(webhook_secret)
+        secret = webhook_secret.sub(/^whsec_/, "")
+        Base64.strict_decode64(secret)
+      rescue ArgumentError => e
+        raise "Failed to decode webhook secret: #{e.message}"
+      end
+
+      # Verify signature using constant-time comparison
+      def verify_signature(signature_header, expected_signature)
+        signatures = signature_header.split(" ")
+        signatures.each do |sig|
+          parts = sig.split(",", 2)
+          next if parts.length != 2
+
+          received_signature = parts[1]
+          return true if secure_compare(expected_signature, received_signature)
+        end
+
+        raise "No matching signature found"
+      end
+
+      # Generate HMAC-SHA256 signature and return it as base64
+      def generate_signature(secret, content)
+        digest = OpenSSL::HMAC.digest("sha256", secret, content)
+        Base64.strict_encode64(digest)
+      end
+
+      # Constant-time string comparison to prevent timing attacks
+      #
+      # Note: We implement this manually for Ruby 2.7 compatibility.
+      # Ruby 3.0+ could use OpenSSL.fixed_length_secure_compare instead.
+      def secure_compare(str_a, str_b)
+        return false if str_a.nil? || str_b.nil? || str_a.bytesize != str_b.bytesize
+
+        bytes_a = str_a.unpack("C*")
+        result = 0
+        str_b.each_byte.with_index { |byte_b, i| result |= byte_b ^ bytes_a[i] }
+        result.zero?
+      end
+    end
+  end
+end

data/lib/sendio.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Version
+require "sendio/version"
+
+# Utils
+require "httparty"
+require "json"
+require "cgi"
+require "erb"
+require "sendio/errors"
+require "sendio/response"
+require "sendio/client"
+require "sendio/request"
+require "sendio/multipart_request"
+require "sendio/pagination_helper"
+
+# API Operations
+require "sendio/segments"
+require "sendio/api_keys"
+require "sendio/broadcasts"
+require "sendio/batch"
+require "sendio/contacts"
+require "sendio/contacts/imports"
+require "sendio/contacts/segments"
+require "sendio/contacts/topics"
+require "sendio/contact_properties"
+require "sendio/domains"
+require "sendio/emails"
+require "sendio/templates"
+require "sendio/emails/receiving"
+require "sendio/emails/attachments"
+require "sendio/emails/receiving/attachments"
+require "sendio/logs"
+require "sendio/mailboxes"
+require "sendio/topics"
+require "sendio/webhooks"
+require "sendio/oauth_grants"
+require "sendio/automations"
+require "sendio/automations/runs"
+require "sendio/automations/templates"
+require "sendio/events"
+require "sendio/suppressions"
+require "sendio/suppressions/batch"
+require "sendio/usage"
+
+# Rails
+require "sendio/railtie" if defined?(Rails) && defined?(ActionMailer)
+require "sendio/action_mailbox" if defined?(Rails) && defined?(ActionMailbox)
+
+# Main Sendio module
+module Sendio
+  DEFAULT_BASE_URL = "https://api.send.io"
+
+  class << self
+    attr_accessor :api_key
+    attr_writer :base_url
+
+    # The API base URL, always returned with a trailing slash.
+    # Resolution order: Sendio.base_url = "...", then ENV["SENDIO_BASE_URL"],
+    # then https://api.send.io. A trailing slash is optional everywhere.
+    def base_url
+      url = @base_url.to_s.strip
+      url = ENV["SENDIO_BASE_URL"].to_s.strip if url.empty?
+      url = DEFAULT_BASE_URL if url.empty?
+      "#{url.sub(%r{/+\z}, "")}/"
+    end
+
+    def configure
+      yield self if block_given?
+      true
+    end
+    alias config configure
+  end
+
+  # @deprecated Use Segments instead
+  Audiences = Segments
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: sendio
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- send.io
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+description: Send and manage email with the send.io API from Ruby and Rails (ActionMailer
+  delivery method included).
+email: support@send.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- NOTICE
+- README.md
+- app/controllers/action_mailbox/ingresses/sendio/inbound_emails_controller.rb
+- lib/sendio.rb
+- lib/sendio/action_mailbox.rb
+- lib/sendio/action_mailbox/engine.rb
+- lib/sendio/action_mailbox/message_builder.rb
+- lib/sendio/api_keys.rb
+- lib/sendio/automations.rb
+- lib/sendio/automations/runs.rb
+- lib/sendio/automations/templates.rb
+- lib/sendio/batch.rb
+- lib/sendio/broadcasts.rb
+- lib/sendio/client.rb
+- lib/sendio/contact_properties.rb
+- lib/sendio/contacts.rb
+- lib/sendio/contacts/imports.rb
+- lib/sendio/contacts/segments.rb
+- lib/sendio/contacts/topics.rb
+- lib/sendio/domains.rb
+- lib/sendio/emails.rb
+- lib/sendio/emails/attachments.rb
+- lib/sendio/emails/receiving.rb
+- lib/sendio/emails/receiving/attachments.rb
+- lib/sendio/errors.rb
+- lib/sendio/events.rb
+- lib/sendio/logs.rb
+- lib/sendio/mailboxes.rb
+- lib/sendio/mailer.rb
+- lib/sendio/multipart_request.rb
+- lib/sendio/oauth_grants.rb
+- lib/sendio/pagination_helper.rb
+- lib/sendio/railtie.rb
+- lib/sendio/request.rb
+- lib/sendio/response.rb
+- lib/sendio/segments.rb
+- lib/sendio/suppressions.rb
+- lib/sendio/suppressions/batch.rb
+- lib/sendio/templates.rb
+- lib/sendio/topics.rb
+- lib/sendio/usage.rb
+- lib/sendio/version.rb
+- lib/sendio/webhooks.rb
+homepage: https://send.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://send.io
+  documentation_uri: https://developer.send.io/docs/api
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: The official Ruby and Rails SDK for send.io
+test_files: []