Add webhook endpoints

README.md

@@ -179,6 +179,7 @@ Email API:
 - 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)
 
 Email Sandbox (Testing):
 

examples/webhooks_api.rb

@@ -0,0 +1,42 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+webhooks_api = Mailtrap::WebhooksAPI.new(account_id, client)
+
+# Create an `email_sending` webhook
+webhook = webhooks_api.create(
+  url: 'https://example.com/mailtrap/webhooks',
+  webhook_type: 'email_sending',
+  payload_format: 'json',
+  sending_stream: 'transactional',
+  event_types: %w[delivery bounce],
+  domain_id: 435
+)
+# => #<struct Mailtrap::Webhook id=1, url="https://example.com/mailtrap/webhooks", ..., signing_secret="a1b2c3...">
+
+# Create an `audit_log` webhook
+webhooks_api.create(
+  url: 'https://example.com/mailtrap/audit-log',
+  webhook_type: 'audit_log'
+)
+
+# List all webhooks
+webhooks_api.list
+# => [#<struct Mailtrap::Webhook id=1, ...>, #<struct Mailtrap::Webhook id=2, ...>]
+
+# Get a single webhook
+webhooks_api.get(webhook.id)
+# => #<struct Mailtrap::Webhook id=1, ...>
+
+# Update webhook
+webhooks_api.update(
+  webhook.id,
+  active: false,
+  event_types: %w[delivery bounce unsubscribe]
+)
+# => #<struct Mailtrap::Webhook id=1, active=false, ...>
+
+# Delete webhook
+webhooks_api.delete(webhook.id)
+# => #<struct Mailtrap::Webhook id=1, ...>

lib/mailtrap.rb

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

lib/mailtrap/webhook.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Webhook
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/8d553c46c2d33-webhooks
+  # @attr_reader id [Integer] The webhook ID
+  # @attr_reader url [String] The URL that will receive webhook payloads
+  # @attr_reader active [Boolean] Whether the webhook is active
+  # @attr_reader webhook_type [String] The type of webhook (`email_sending` or `audit_log`)
+  # @attr_reader payload_format [String] The webhook payload format (`json` or `jsonlines`)
+  # @attr_reader sending_stream [String, nil] The sending stream (`transactional` or `bulk`).
+  #   Applicable only for `email_sending` webhooks.
+  # @attr_reader domain_id [Integer, nil] The sending domain ID the webhook is scoped to,
+  #   or nil for all domains. Applicable only for `email_sending` webhooks.
+  # @attr_reader event_types [Array<String>] The event types the webhook is subscribed to.
+  #   Applicable only for `email_sending` webhooks.
+  # @attr_reader signing_secret [String, nil] HMAC SHA-256 signing secret. Returned only on creation.
+  Webhook = Struct.new(
+    :id,
+    :url,
+    :active,
+    :webhook_type,
+    :payload_format,
+    :sending_stream,
+    :domain_id,
+    :event_types,
+    :signing_secret,
+    keyword_init: true
+  )
+end

lib/mailtrap/webhooks_api.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'webhook'
+
+module Mailtrap
+  class WebhooksAPI
+    include BaseAPI
+
+    self.supported_options = %i[url webhook_type active payload_format sending_stream event_types domain_id]
+
+    self.response_class = Webhook
+
+    # Lists all webhooks for the account
+    # @return [Array<Webhook>] Array of webhooks
+    # @!macro api_errors
+    def list
+      response = client.get(base_path)
+      response[:data].map { |item| build_entity(item, response_class) }
+    end
+
+    # Retrieves a specific webhook
+    # @param webhook_id [Integer] The webhook ID
+    # @return [Webhook] Webhook object
+    # @!macro api_errors
+    def get(webhook_id)
+      base_get(webhook_id)
+    end
+
+    # Creates a new webhook
+    # @param [Hash] options The parameters to create
+    # @option options [String] :url The URL that will receive webhook payloads
+    # @option options [String] :webhook_type The type of webhook (`email_sending` or `audit_log`)
+    # @option options [Boolean] :active Whether the webhook is active. Defaults to true.
+    # @option options [String] :payload_format Payload format (`json` or `jsonlines`). Defaults to `json`.
+    # @option options [String] :sending_stream Sending stream (`transactional` or `bulk`).
+    #   Required for `email_sending` webhook type.
+    # @option options [Array<String>] :event_types Event types to subscribe to.
+    #   Required for `email_sending` webhook type.
+    # @option options [Integer] :domain_id Sending domain ID to scope the webhook to.
+    #   Applicable only for `email_sending` webhooks.
+    # @return [Webhook] Created webhook (includes `signing_secret`)
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing webhook
+    # @param webhook_id [Integer] The webhook ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :url The URL that will receive webhook payloads
+    # @option options [Boolean] :active Whether the webhook is active
+    # @option options [String] :payload_format Payload format (`json` or `jsonlines`)
+    # @option options [Array<String>] :event_types Event types to subscribe to.
+    #   Applicable only for `email_sending` webhooks.
+    # @return [Webhook] Updated webhook
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(webhook_id, options)
+      base_update(webhook_id, options, %i[url active payload_format event_types])
+    end
+
+    # Deletes a webhook
+    # @param webhook_id [Integer] The webhook ID
+    # @return [Webhook] Deleted webhook
+    # @!macro api_errors
+    def delete(webhook_id)
+      response = client.delete("#{base_path}/#{webhook_id}")
+      handle_response(response) if response
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/webhooks"
+    end
+
+    def wrap_request(options)
+      { webhook: options }
+    end
+
+    def handle_response(response)
+      build_entity(response[:data], response_class)
+    end
+  end
+end