assinafy 1.5.0

data/lib/assinafy/resources/template_resource.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # Templates — reusable document blueprints with roles and field placements.
+    #
+    # See https://api.assinafy.com.br/v1/docs#template for the documentation
+    # of the Template Object and its related endpoints.
+    class TemplateResource < BaseResource
+      # List templates with pagination metadata.
+      #
+      # @param params [Hash] documented `search`, `page`, and `per_page` query parameters
+      # @param account_id_override [String, nil]
+      # @return [Hash{Symbol=>Array,Hash}] `{ data: [Template, ...], meta: { current_page:, per_page:, ... } }`
+      # @see GET /accounts/{account_id}/templates
+      #
+      # @example Search templates and read pagination metadata
+      #   client.templates.list(search: 'contract', per_page: 3)
+      #   # Returns the unwrapped { data:, meta: } payload:
+      #   # {
+      #   #   data: [
+      #   #     {
+      #   #       "id" => "fa7f3e524f3a2cc00a5ea4325e2",
+      #   #       "name" => "sample-contract-one-page.pdf",
+      #   #       "document_name" => "sample-contract-one-page.pdf",
+      #   #       "message" => nil,
+      #   #       "status" => "Ready",
+      #   #       "pages" => [{ "id" => "fa7f3e528d77f2b3ed786df2ce0", "number" => 1, "fields" => [] }],
+      #   #       "roles" => [{ "id" => "fa7f3e525bfefc71df3701eac6f", "name" => "TemplateEditor" }],
+      #   #       "tags" => [{ "id" => "fa8c09f3e709a8a1c82d69b1454", "name" => "HR" }],
+      #   #       "created_at" => "2024-07-19T15:23:03Z",
+      #   #       "updated_at" => "2024-07-19T15:23:03Z"
+      #   #     }
+      #   #     # ... (each entry is a Template Object; see docs for full shape)
+      #   #   ],
+      #   #   meta: { current_page: 1, per_page: 3, total: 0, last_page: 0 }
+      #   # }
+      def list(params = {}, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+
+        call_list('Failed to list templates') do
+          http_get("accounts/#{acc_id}/templates", params)
+        end
+      end
+
+      # Fetch a template by ID.
+      #
+      # @param template_id         [String]
+      # @param account_id_override [String, nil]
+      # @return [Hash] the unwrapped Template Object
+      # @see GET /accounts/{account_id}/templates/{template_id}
+      #
+      # @example Fetch a single template (includes default_document_tags, omitted from #list)
+      #   client.templates.get('fa7f3e524f3a2cc00a5ea4325e2')
+      #   # Returns the unwrapped Template Object:
+      #   # {
+      #   #   "resource" => "template",
+      #   #   "id" => "fa7f3e524f3a2cc00a5ea4325e2",
+      #   #   "name" => "sample-contract-one-page.pdf",
+      #   #   "document_name" => "sample-contract-one-page.pdf",
+      #   #   "message" => nil,
+      #   #   "status" => "Ready",
+      #   #   "pages" => [
+      #   #     {
+      #   #       "id" => "fa7f3e528d77f2b3ed786df2ce0", "number" => 1, "height" => 2100, "width" => 1275,
+      #   #       "download_url" => "https://api.assinafy.com.br/v1/accounts/1a/templates/.../pages/.../download",
+      #   #       "fields" => []
+      #   #     }
+      #   #   ],
+      #   #   "roles" => [{ "id" => "fa7f3e525bfe", "name" => "TemplateEditor", "assignment_type" => "Editor" }],
+      #   #   "tags" => [{ "id" => "fa8c09f3e709a8a1c82d69b1454", "name" => "HR" }],
+      #   #   "default_document_tags" => [],
+      #   #   "created_at" => "2024-07-19T15:23:03Z",
+      #   #   "updated_at" => "2024-07-19T15:23:03Z"
+      #   # }
+      def get(template_id, account_id_override = nil)
+        acc_id  = account_id(account_id_override)
+        tmpl_id = require_id(template_id, 'Template ID')
+
+        call('Failed to fetch template') do
+          http_get("accounts/#{acc_id}/templates/#{tmpl_id}")
+        end
+      end
+
+      # Create a template by uploading a source document. The endpoint requires a
+      # `multipart/form-data` file upload (verified live) — the template name
+      # defaults to the uploaded file's name and an `Editor` role is created
+      # automatically.
+      #
+      # @param source [String, Hash] a path to a PDF, or a Hash with `:file_path`
+      #   (path) **or** `:buffer` + `:file_name` (raw bytes).
+      # @param options [Hash] additional multipart form fields (e.g. `:message`)
+      # @param account_id_override [String, nil]
+      # @return [Hash] the unwrapped Template Object for the created template
+      # @see POST /accounts/{account_id}/templates
+      #
+      # @example Create a template from a PDF on disk
+      #   client.templates.create('/path/to/contract.pdf')
+      #   # Request: POST /accounts/{account_id}/templates (multipart/form-data)
+      #   # Body: file=<binary application/pdf>
+      #   # Returns the unwrapped Template Object:
+      #   # {
+      #   #   "resource" => "template",
+      #   #   "id" => "103b0275c2bb53a437c761ec3462",
+      #   #   "name" => "contract.pdf",
+      #   #   "document_name" => "contract.pdf",
+      #   #   "message" => nil,
+      #   #   "status" => "Uploaded",
+      #   #   "pages" => [],
+      #   #   "roles" => [{ "id" => "103b0275db76f02f0531db15b62a", "name" => "TemplateEditor",
+      #   #                 "assignment_type" => "Editor", "created_at" => "2026-07-20T15:57:19Z",
+      #   #                 "updated_at" => "2026-07-20T15:57:19Z" }],
+      #   #   "tags" => [],
+      #   #   "created_at" => "2026-07-20T15:57:18Z",
+      #   #   "updated_at" => "2026-07-20T15:57:19Z"
+      #   # }
+      def create(source, options = {}, account_id_override = nil)
+        acc_id            = account_id(account_id_override)
+        buffer, file_name = read_source(source)
+
+        payload = { file: file_part(buffer, file_name) }
+        options.each { |key, value| payload[key.to_s] = value unless value.nil? }
+
+        call('Failed to create template') do
+          http_post("accounts/#{acc_id}/templates", payload)
+        end
+      end
+
+      # Update a template.
+      #
+      # @param template_id         [String]
+      # @param payload             [Hash]
+      # @param account_id_override [String, nil]
+      # @return [Hash] the unwrapped Template Object for the updated template
+      # @see PUT /accounts/{account_id}/templates/{template_id}
+      #
+      # @example Rename a template and set its default invitation message
+      #   client.templates.update('fa7f3e524f3a2cc00a5ea4325e2', name: 'Renamed', message: 'Please sign')
+      #   # JSON body sent: { "name": "Renamed", "message": "Please sign" }
+      #   # Returns the unwrapped Template Object:
+      #   # {
+      #   #   "resource" => "template",
+      #   #   "id" => "fa7f3e524f3a2cc00a5ea4325e2",
+      #   #   "name" => "Renamed",
+      #   #   "document_name" => "sample-contract-one-page.pdf",
+      #   #   "message" => "Please sign",
+      #   #   "status" => "Ready",
+      #   #   "created_at" => "2024-07-19T15:23:03Z",
+      #   #   "updated_at" => "2024-07-19T16:00:00Z"
+      #   #   # ... (full Template Object: pages, roles, tags; see docs for full shape)
+      #   # }
+      def update(template_id, payload, account_id_override = nil)
+        acc_id  = account_id(account_id_override)
+        tmpl_id = require_id(template_id, 'Template ID')
+        body    = body_params(require_payload(payload, 'Template payload'))
+
+        call('Failed to update template') do
+          http_put("accounts/#{acc_id}/templates/#{tmpl_id}", body)
+        end
+      end
+
+      # Delete a template.
+      #
+      # @param template_id         [String]
+      # @param account_id_override [String, nil]
+      # @return [nil] always nil on success (the SDK discards the envelope body)
+      # @raise [Assinafy::ApiError] 404 "Template não encontrado." when the template ID does not exist
+      # @see DELETE /accounts/{account_id}/templates/{template_id}
+      #
+      # @example Delete a template
+      #   client.templates.delete('fa7f3e524f3a2cc00a5ea4325e2')
+      #   # => nil
+      #
+      # @example Deleting an unknown template raises
+      #   client.templates.delete('does-not-exist')
+      #   # raises Assinafy::ApiError (status 404, message "Template não encontrado.")
+      def delete(template_id, account_id_override = nil)
+        acc_id  = account_id(account_id_override)
+        tmpl_id = require_id(template_id, 'Template ID')
+
+        call_void('Failed to delete template') do
+          http_delete("accounts/#{acc_id}/templates/#{tmpl_id}")
+        end
+      end
+
+      # Download a rendered template page image as raw bytes. The page IDs come
+      # from the Template Page Objects on {#get} (each carries a `download_url`).
+      #
+      # @param template_id         [String]
+      # @param page_id             [String]
+      # @param account_id_override [String, nil]
+      # @return [String] the raw image bytes (ASCII-8BIT/binary), not the JSON envelope
+      # @raise [Assinafy::ApiError] 404 'Template "{id}" não encontrado.' when the template or page is unknown
+      # @see GET /accounts/{account_id}/templates/{template_id}/pages/{page_id}/download
+      #
+      # @example Download a page image and write it to disk
+      #   bytes = client.templates.download_page('fa7f3e524f3a2cc00a5ea4325e2', 'fa7f3e528d77f2b3ed786df2ce0')
+      #   # => "\x89PNG\r\n\x1A\n..." (raw binary String, encoding ASCII-8BIT)
+      #   File.binwrite('page-1.png', bytes)
+      #
+      # @example Downloading an unknown page raises
+      #   client.templates.download_page('bad-id', 'bad-page')
+      #   # raises Assinafy::ApiError (status 404, message 'Template "{id}" não encontrado.')
+      def download_page(template_id, page_id, account_id_override = nil)
+        acc_id  = account_id(account_id_override)
+        tmpl_id = require_id(template_id, 'Template ID')
+        pid     = require_id(page_id, 'Page ID')
+
+        call_binary('Failed to download template page') do
+          http_get("accounts/#{acc_id}/templates/#{tmpl_id}/pages/#{pid}/download")
+        end
+      end
+    end
+  end
+end

data/lib/assinafy/resources/user_resource.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # The authenticated user's own profile and cross-account KPIs.
+    #
+    # See https://api.assinafy.com.br/v1/docs for the User Object.
+    class UserResource < BaseResource
+      NOTIFICATION_PREFERENCE_CODES = %w[
+        DocumentCompleted
+        SignerDeclined
+        DocumentCancelled
+        DocumentAboutToExpire
+        DocumentExpired
+        DocumentExpirationReset
+        DocumentProcessingFailed
+        TemplateProcessingFailed
+        SignerWhatsappFailed
+      ].freeze
+
+      # Fetch the authenticated user's profile. The current OpenAPI response is
+      # an `AuthUser` directly, while some sandbox deployments return the login-like
+      # `{ 'user' => AuthUser, 'accounts' => [...] }` shape. The SDK does not reshape
+      # either form; it returns the envelope's `data` value unchanged.
+      #
+      # @return [Hash{String=>Object}] an AuthUser Hash, or the sandbox
+      #   `{ 'user' => {..}, 'accounts' => [{..}] }` form
+      # @see GET /users/self
+      # @example Fetch the current user
+      #   # Request: GET /users/self
+      #   client.users.me
+      #
+      #   # Current OpenAPI response (unwrapped data payload):
+      #   {
+      #     'id' => 'user-id',
+      #     'name' => 'Example User',
+      #     'email' => 'user@example.com',
+      #     'telephone' => nil,
+      #     'government_id' => '',
+      #     'is_email_verified' => true,
+      #     'has_accepted_terms' => true,
+      #     'is_password_set' => true,
+      #     'created_at' => '2026-05-12T18:05:11Z',
+      #     'to_be_deleted_at' => nil
+      #   }
+      #
+      #   # Shape returned by some sandbox deployments (also passed through unchanged):
+      #   {
+      #     'user' => {
+      #       'id' => 'user-id',
+      #       'name' => 'Example User',
+      #       'email' => 'user@example.com',
+      #       'telephone' => nil,
+      #       'government_id' => '',
+      #       'is_email_verified' => true,
+      #       'has_accepted_terms' => true,
+      #       'is_password_set' => true,
+      #       'created_at' => '2026-05-12T18:05:11Z',
+      #       'to_be_deleted_at' => nil
+      #     },
+      #     'accounts' => [
+      #       {
+      #         'id' => 'account-id',
+      #         'name' => 'Example Workspace',
+      #         'roles' => ['owner'],
+      #         'is_delete_allowed' => true,
+      #         'created_at' => '2026-05-12T18:05:11Z'
+      #       }
+      #     ]
+      #   }
+      def me
+        call('Failed to fetch current user') do
+          http_get('users/self')
+        end
+      end
+
+      # Fetch the authenticated user's cross-account document KPIs.
+      #
+      # @note Documented in the API reference but not enabled on every
+      #   environment — the sandbox currently returns 404 for this route.
+      # @param granularity [String, nil] `"monthly"` or `"daily"`
+      # @param month       [String, nil] e.g. `"2026-06"`
+      # @return [Array<Hash>] one KPI entry per period
+      # @see GET /users/self/stats
+      # @example Fetch monthly cross-account KPIs
+      #   # Request: GET /users/self/stats?granularity=monthly
+      #   client.users.stats(granularity: 'monthly')
+      #
+      #   # Response (unwrapped data payload):
+      #   [
+      #     {
+      #       'period' => '2026-06',
+      #       'documents_uploaded' => 42,
+      #       'documents_sent' => 37,
+      #       'signature_requests' => 61,
+      #       'signature_requests_email' => 45,
+      #       'signature_requests_whatsapp' => 16,
+      #       'signature_requests_viewed' => 58,
+      #       'signature_requests_completed' => 52,
+      #       'documents_certified' => 34
+      #     }
+      #   ]
+      def stats(granularity: nil, month: nil)
+        call('Failed to fetch user stats') do
+          http_get('users/self/stats', query_params(granularity: granularity, month: month))
+        end
+      end
+
+      # Fetch all owner-facing document email preferences. All nine keys are
+      # returned and default to true. Account and security email is not
+      # configurable through this endpoint.
+      #
+      # @return [Hash{String=>Boolean}] all nine documented preference codes
+      # @see GET /users/self/notification-preferences
+      # @example Fetch the current preferences
+      #   # Request: GET /users/self/notification-preferences
+      #
+      #   # Response (unwrapped data payload):
+      #   {
+      #     'DocumentCompleted' => true,
+      #     'SignerDeclined' => true,
+      #     'DocumentCancelled' => true,
+      #     'DocumentAboutToExpire' => true,
+      #     'DocumentExpired' => true,
+      #     'DocumentExpirationReset' => true,
+      #     'DocumentProcessingFailed' => true,
+      #     'TemplateProcessingFailed' => true,
+      #     'SignerWhatsappFailed' => true
+      #   }
+      def notification_preferences
+        call('Failed to fetch notification preferences') do
+          http_get('users/self/notification-preferences')
+        end
+      end
+
+      # Merge selected owner-facing document email preferences.
+      #
+      # Omitted keys keep their current values. The API returns the full
+      # nine-key map shown by {#notification_preferences}.
+      #
+      # @param preferences [Hash{String,Symbol=>Boolean}] non-empty partial map
+      # @return [Hash{String=>Boolean}] the full updated map
+      # @see PUT /users/self/notification-preferences
+      # @example Disable one notification
+      #   client.users.update_notification_preferences(SignerDeclined: false)
+      #
+      #   # Request: PUT /users/self/notification-preferences
+      #   # Body: { "SignerDeclined": false }
+      #
+      #   # Response (the full unwrapped preference map):
+      #   {
+      #     'DocumentCompleted' => true,
+      #     'SignerDeclined' => false,
+      #     'DocumentCancelled' => true,
+      #     'DocumentAboutToExpire' => true,
+      #     'DocumentExpired' => true,
+      #     'DocumentExpirationReset' => true,
+      #     'DocumentProcessingFailed' => true,
+      #     'TemplateProcessingFailed' => true,
+      #     'SignerWhatsappFailed' => true
+      #   }
+      def update_notification_preferences(preferences)
+        preferences = require_payload(preferences, 'Notification preferences')
+        raise ValidationError.new('At least one notification preference is required') if preferences.empty?
+
+        preferences.each do |code, enabled|
+          code = code.to_s
+          unless NOTIFICATION_PREFERENCE_CODES.include?(code)
+            raise ValidationError.new("Unknown notification preference: #{code}")
+          end
+          unless [true, false].include?(enabled)
+            raise ValidationError.new("Notification preference #{code} must be boolean")
+          end
+        end
+
+        call('Failed to update notification preferences') do
+          http_put('users/self/notification-preferences', body_params(preferences))
+        end
+      end
+    end
+  end
+end

data/lib/assinafy/resources/webhook_resource.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # Webhook subscription, event-type catalog, delivery history, and retries.
+    #
+    # See https://api.assinafy.com.br/v1/docs#webhooks for the full
+    # documentation of these endpoints.
+    class WebhookResource < BaseResource
+      # Create or replace the account's webhook subscription. The API uses
+      # `PUT subscriptions` for both create and update semantics, hence the
+      # name `register` (with an `update` alias).
+      #
+      # @param payload [Hash]
+      # @option payload [String]        :url       endpoint that will receive events
+      # @option payload [String]        :email     contact email for delivery health
+      # @option payload [Array<String>] :events    event-type IDs (see {#list_event_types})
+      # @option payload [Boolean]       :is_active default `true` when omitted
+      # @param account_id_override [String, nil]
+      # @return [Hash] the subscription object: { events:, is_active:, url:, email:, updated_at: }
+      # @see PUT /accounts/{account_id}/webhooks/subscriptions
+      # @example Register (or replace) the subscription
+      #   client.webhooks.register(
+      #     url:    'https://example.com/webhook',
+      #     email:  'ops@example.com',
+      #     events: %w[document_ready document_prepared]
+      #   )
+      #   # PUT /accounts/{account_id}/webhooks/subscriptions
+      #   # request body sent by the SDK:
+      #   # {
+      #   #   "url":       "https://example.com/webhook",
+      #   #   "email":     "ops@example.com",
+      #   #   "events":    ["document_ready", "document_prepared"],
+      #   #   "is_active": true
+      #   # }
+      #   # => unwrapped data payload returned:
+      #   # {
+      #   #   events:     ["document_ready", "document_prepared"],
+      #   #   is_active:  true,
+      #   #   url:        "https://example.com/webhook",
+      #   #   email:      "ops@example.com",
+      #   #   updated_at: "2026-06-05T21:13:24Z"
+      #   # }
+      def register(payload, account_id_override = nil)
+        p = require_payload(payload, 'Webhook payload').transform_keys(&:to_sym)
+
+        raise ValidationError.new('Webhook URL is required')   if p[:url].to_s.strip.empty?
+        raise ValidationError.new('Webhook email is required') if p[:email].to_s.strip.empty?
+
+        events = require_array(p[:events], 'Webhook events')
+        unless events.all? { |event| event.is_a?(String) && !event.strip.empty? }
+          raise ValidationError.new('Webhook events must be non-empty Strings')
+        end
+
+        acc_id = account_id(account_id_override)
+
+        body = {
+          url:       p[:url],
+          email:     p[:email],
+          events:    events,
+          is_active: p.key?(:is_active) ? require_boolean(p[:is_active], 'is_active') : true
+        }
+
+        @logger.info('Registering webhook subscription')
+
+        call('Failed to register webhook') do
+          http_put("accounts/#{acc_id}/webhooks/subscriptions", body_params(body))
+        end
+      end
+
+      alias update register
+
+      # Fetch the current webhook subscription. Returns `nil` on 404
+      # (no subscription configured yet).
+      #
+      # @param account_id_override [String, nil]
+      # @return [Hash, nil] subscription object, or `nil` when none is configured (404)
+      # @see GET /accounts/{account_id}/webhooks/subscriptions
+      # @example Fetch the current subscription
+      #   client.webhooks.get
+      #   # GET /accounts/{account_id}/webhooks/subscriptions
+      #   # => unwrapped data payload returned (nil if no subscription exists):
+      #   # {
+      #   #   events:     ["document_ready", "signer_signed_document"],
+      #   #   is_active:  false,
+      #   #   url:        "https://example.com/sdk-smoke-webhook",
+      #   #   email:      "webhook@example.com",
+      #   #   updated_at: "2026-06-05T21:13:24Z"
+      #   # }
+      def get(account_id_override = nil)
+        acc_id = account_id(account_id_override)
+
+        call_optional('Failed to fetch webhook subscription') do
+          http_get("accounts/#{acc_id}/webhooks/subscriptions")
+        end
+      end
+
+      # Inactivate (but keep) the account's webhook subscription. Stops
+      # deliveries without losing the configured event set.
+      #
+      # @param account_id_override [String, nil]
+      # @return [Hash] the subscription object with `is_active: false`; the event set is preserved
+      # @see PUT /accounts/{account_id}/webhooks/inactivate
+      # @example Inactivate without losing the configured events
+      #   client.webhooks.inactivate
+      #   # PUT /accounts/{account_id}/webhooks/inactivate  (no request body)
+      #   # => unwrapped data payload returned:
+      #   # {
+      #   #   events:     ["document_ready", "document_prepared"],
+      #   #   is_active:  false,
+      #   #   url:        "https://example.com/webhook",
+      #   #   email:      "ops@example.com",
+      #   #   updated_at: "2026-06-05T21:13:24Z"
+      #   # }
+      def inactivate(account_id_override = nil)
+        acc_id = account_id(account_id_override)
+
+        @logger.info('Inactivating webhook subscription')
+
+        call('Failed to inactivate webhook subscription') do
+          http_put("accounts/#{acc_id}/webhooks/inactivate")
+        end
+      end
+
+      # Catalogue of supported event-type identifiers.
+      #
+      # @return [Array<Hash>] each entry is { id:, description: } (18 event types available)
+      # @see GET /webhooks/event-types
+      # @example List subscribable event types
+      #   client.webhooks.list_event_types
+      #   # GET /webhooks/event-types
+      #   # => unwrapped data payload returned (18 entries):
+      #   # [
+      #   #   { id: "document_uploaded",        description: "Triggered when the User has uploaded a Document" },
+      #   #   { id: "document_metadata_ready",  description: "Triggered when the document is ready to be prepared..." },
+      #   #   { id: "document_prepared",        description: "Triggered when the User prepares a Document." },
+      #   #   { id: "assignment_created",       description: "Triggered when the User created an assignment..." },
+      #   #   { id: "signature_requested",      description: "Triggered when the User requested signature..." },
+      #   #   { id: "document_ready",           description: "Triggered when the last Signer signs the Document..." },
+      #   #   { id: "signer_created",           description: "Triggered when the User created a Signer" },
+      #   #   { id: "signer_email_verified",    description: "Triggered when Signer's email has been verified..." }
+      #   #   # ... (see docs for the full 18-event catalogue)
+      #   # ]
+      def list_event_types
+        call('Failed to list webhook event types') do
+          http_get('webhooks/event-types')
+        end
+      end
+
+      # List webhook delivery attempts (dispatches) with pagination metadata.
+      #
+      # @param params [Hash] `event`, `delivered`, `from`, `to`, `page`, `per-page`
+      # @param account_id_override [String, nil]
+      # @return [Hash{Symbol=>Array,Hash}] `{ data: [dispatch, ...], meta: { current_page:, per_page:, total:,
+      #   last_page: } }`
+      # @see GET /accounts/{account_id}/webhooks
+      # @example List delivery attempts, filtered to undelivered
+      #   client.webhooks.list_dispatches(delivered: false, 'per-page': 20)
+      #   # GET /accounts/{account_id}/webhooks?delivered=false&per-page=20
+      #   # => unwrapped data payload returned (pagination from x-pagination-* headers):
+      #   # {
+      #   #   data: [
+      #   #     {
+      #   #       id:            "dispatch-id",
+      #   #       event:         "signature_requested",
+      #   #       activity_id:   15431,
+      #   #       endpoint:      "https://example.com/webhook",
+      #   #       payload:       { id: 15431, event: "signature_requested", object: {}, subject: {}, payload: {} },
+      #   #       delivered:     false,
+      #   #       http_status:   404,
+      #   #       response_body: "{\"success\":false,...}",
+      #   #       error:         "Client error: `POST https://example.com/webhook` resulted in a 404 ...",
+      #   #       created_at:    "2026-07-20T15:57:38Z",
+      #   #       updated_at:    "2026-07-20T15:57:38Z"
+      #   #     }
+      #   #     # ... (see docs for full dispatch shape)
+      #   #   ],
+      #   #   meta: { current_page: 1, per_page: 20, total: 2, last_page: 1 }
+      #   # }
+      def list_dispatches(params = {}, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+
+        call_list('Failed to list webhook dispatches') do
+          http_get("accounts/#{acc_id}/webhooks", params)
+        end
+      end
+
+      # Force a single dispatch to be re-attempted.
+      #
+      # @param dispatch_id [String]
+      # @param account_id_override [String, nil]
+      # @return [Hash] the freshly created dispatch entry (same shape as {#list_dispatches}, plus `resource`)
+      # @see POST /accounts/{account_id}/webhooks/{dispatch_id}/retry
+      # @example Force a single dispatch to be re-attempted
+      #   client.webhooks.retry_dispatch('dispatch-id')
+      #   # POST /accounts/{account_id}/webhooks/dispatch-id/retry  (no request body)
+      #   # => unwrapped data payload returned:
+      #   # {
+      #   #   resource:      "activity_dispatching_history",
+      #   #   id:            "dispatch-id",
+      #   #   event:         "signature_requested",
+      #   #   activity_id:   15431,
+      #   #   endpoint:      "https://example.com/webhook",
+      #   #   payload:       { id: 15431, event: "signature_requested", object: {}, subject: {} },
+      #   #   delivered:     true,
+      #   #   http_status:   200,
+      #   #   response_body: "OK",
+      #   #   error:         nil,
+      #   #   created_at:    "2026-07-20T15:57:38Z",
+      #   #   updated_at:    "2026-07-20T15:57:39Z"
+      #   # }
+      def retry_dispatch(dispatch_id, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        did    = require_id(dispatch_id, 'Dispatch ID')
+
+        call('Failed to retry webhook dispatch') do
+          http_post("accounts/#{acc_id}/webhooks/#{did}/retry")
+        end
+      end
+    end
+  end
+end