mailchimp-rest-api 0.3.0 → 0.4.1

data/lib/mailchimp-api/resources/audience/interests.rb

@@ -2,35 +2,101 @@
 
 module MailchimpAPI
   module Audience
+    # Provides methods for interacting with Mailchimp interests
+    # Interests allow subscribers to opt into specific content categories
     class Interests < Resource
+      # Module with endpoints for Interests APIs
       module APIs
         include Pagination::ListEachItemHelper
 
+        # List all interests in a specific interest category
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing interests
+        # @example Get all interests in a category
+        #   interests.list('list123', 'category456')
         def list(list_id, interest_category_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Create a new interest
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Interest attributes
+        # @option body [String] :name The name of the interest
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing the created interest
+        # @example Create a new interest
+        #   interests.create('list123', 'category456', body: {
+        #     name: 'Product Updates'
+        #   })
         def create(list_id, interest_category_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests"
           client.post(path, query: query, body: body, headers: headers)
         end
 
+        # Show details for a specific interest
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category
+        # @param interest_id [String] The ID of the interest
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing interest details
+        # @example Get details for an interest
+        #   interests.show('list123', 'category456', 'interest789')
         def show(list_id, interest_category_id, interest_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests/#{interest_id}"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Delete an interest
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category
+        # @param interest_id [String] The ID of the interest to delete
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Boolean] True if successful
+        # @example Delete an interest
+        #   interests.delete('list123', 'category456', 'interest789')
         def delete(list_id, interest_category_id, interest_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests/#{interest_id}"
           client.delete(path, query: query, body: body, headers: headers)
         end
 
+        # Update an interest
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category
+        # @param interest_id [String] The ID of the interest to update
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Updated interest attributes
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing updated interest
+        # @example Update an interest name
+        #   interests.update('list123', 'category456', 'interest789', body: {
+        #     name: 'Updated Interest Name'
+        #   })
         def update(list_id, interest_category_id, interest_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests/#{interest_id}"
           client.patch(path, query: query, body: body, headers: headers)
         end
 
+        # Iterate through all interests in an interest category
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @yield [Hash] Each interest
+        # @example Iterate through interest in category
+        #   interests.each('list123') do |interest|
+        #     puts interest[:name]
+        #   end
         def each(list_id, interest_category_id, query: nil, body: nil, headers: nil, &block)
           list_each_item(:interests, list_id, interest_category_id, query: query, body: body, headers: headers, &block)
         end

data/lib/mailchimp-api/resources/audience/member_tags.rb

@@ -2,27 +2,64 @@
 
 module MailchimpAPI
   module Audience
+    # Provides methods for interacting with Mailchimp member tags
+    # Tags help organize and segment your subscribers
     class MemberTags < Resource
+      # Module with endpoints for MemberTags APIs
       module APIs
         include Pagination::ListEachItemHelper
+        include MailchimpAPI::Audience::Utils
 
+        # List all tags for a specific member
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing member tags
+        # @example Get all tags for a member
+        #   member_tags.list('list123', 'user@example.com')
         def list(list_id, email, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members/#{subscriber_hash(email)}/tags"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Add or update tags for a member
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Tags to add/update
+        # @option body [Array<Hash>] :tags Array of tag objects
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing update status
+        # @example Add tags to a member
+        #   member_tags.create('list123', 'user@example.com', body: {
+        #     tags: [
+        #       { name: 'Customer', status: 'active' },
+        #       { name: 'VIP', status: 'active' }
+        #     ]
+        #   })
         def create(list_id, email, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members/#{subscriber_hash(email)}/tags"
           client.post(path, query: query, body: body, headers: headers)
         end
 
+        # Iterate through all tags for a member
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @yield [Hash] Each member tag
+        # @example Iterate through member tags
+        #   member_tags.each('list123', 'user@example.com') do |tag|
+        #     puts tag[:name]
+        #   end
         def each(list_id, email, query: nil, body: nil, headers: nil, &block)
           list_each_item(:tags, list_id, email, query: query, body: body, headers: headers, &block)
         end
       end
 
-      include MailchimpAPI::Audience::Utils
-      extend MailchimpAPI::Audience::Utils
       include APIs
       extend APIs
     end

data/lib/mailchimp-api/resources/audience/members.rb

@@ -1,53 +1,143 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
+  # Contains classes related to Audiences APIs collection
   module Audience
+    # Provides methods for interacting with Mailchimp list members
+    # Members are subscribers who belong to a Mailchimp list
     class Members < Resource
+      # Module with endpoints for Members APIs
       module APIs
         include Pagination::ListEachItemHelper
+        include MailchimpAPI::Audience::Utils
 
+        # List all members in a specific list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @option query [Integer] :count Number of records to return (default: 10)
+        # @option query [Integer] :offset Number of records to skip (default: 0)
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing list members
+        # @example Get first 10 members of a list
+        #   members.list('list123')
+        # @example Get members 11-20
+        #   members.list('list123', query: { count: 10, offset: 10 })
         def list(list_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Add a new member to a list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Member attributes
+        # @option body [String] :email_address The member's email address
+        # @option body [String] :status Subscription status (subscribed, unsubscribed, etc.)
+        # @option body [Hash] :merge_fields Merge fields like FNAME, LNAME
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing the created member
+        # @example Add a new subscriber
+        #   members.create('list123', body: {
+        #     email_address: 'new@example.com',
+        #     status: 'subscribed',
+        #     merge_fields: { FNAME: 'John', LNAME: 'Doe' }
+        #   })
         def create(list_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members"
           client.post(path, query: query, body: body, headers: headers)
         end
 
+        # Show details for a specific member
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing member details
+        # @example Get member details
+        #   members.show('list123', 'user@example.com')
         def show(list_id, email, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members/#{subscriber_hash(email)}"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Archive a list member (soft delete)
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Boolean] True if successful
+        # @example Archive a member
+        #   members.archive('list123', 'user@example.com')
         def archive(list_id, email, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members/#{subscriber_hash(email)}"
           client.delete(path, query: query, body: body, headers: headers)
         end
 
+        # Update a list member
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Updated member attributes
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing updated member
+        # @example Update member status
+        #   members.update('list123', 'user@example.com', body: {
+        #     status: 'unsubscribed'
+        #   })
         def update(list_id, email, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members/#{subscriber_hash(email)}"
           client.patch(path, query: query, body: body, headers: headers)
         end
 
+        # Add or update a list member
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Member attributes
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing the member
+        # @example Add or update a member
+        #   members.add_or_update('list123', 'user@example.com', body: {
+        #     status: 'subscribed',
+        #     merge_fields: { FNAME: 'Updated Name' }
+        #   })
         def add_or_update(list_id, email, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members/#{subscriber_hash(email)}"
           client.put(path, query: query, body: body, headers: headers)
         end
 
+        # Permanently delete a list member
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param email [String] The member's email address
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Boolean] True if successful
+        # @example Permanently delete a member
+        #   members.delete_permanent('list123', 'user@example.com')
         def delete_permanent(list_id, email, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/members/#{subscriber_hash(email)}/actions/delete-permanent"
           client.post(path, query: query, body: body, headers: headers)
         end
 
+        # Iterate through all members in a list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @yield [Hash] Each list member
+        # @example Iterate through list members
+        #   members.each('list123') do |member|
+        #     puts member[:email_address]
+        #   end
         def each(list_id, query: nil, body: nil, headers: nil, &block)
           list_each_item(:members, list_id, query: query, body: body, headers: headers, &block)
         end
       end
 
-      include MailchimpAPI::Audience::Utils
-      extend MailchimpAPI::Audience::Utils
       include APIs
       extend APIs
     end

data/lib/mailchimp-api/resources/audience/segment_members.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Audience
+    # Provides methods for interacting with Mailchimp segment members
+    # Segment members are subscribers who belong to a specific segment
+    class SegmentMembers < Resource
+      # Module with endpoints for SegmentMembers APIs
+      module APIs
+        include Pagination::ListEachItemHelper
+        include MailchimpAPI::Audience::Utils
+
+        # List all members in a specific segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing segment members
+        # @example Get all members in a segment
+        #   segment_members.list('list123', 'segment456')
+        def list(list_id, segment_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments/#{segment_id}/members"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        # Add a member to a static segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Member details
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing the added member
+        # @example Add a member to a segment
+        #   segment_members.create('list123', 'segment456', body: {
+        #     email_address: 'new@example.com'
+        #   })
+        def create(list_id, segment_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments/#{segment_id}/members"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+
+        # Remove a member from a static segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment
+        # @param email [String] The email address of the member to remove
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Boolean] True if successful
+        # @example Remove a member from a segment
+        #   segment_members.delete('list123', 'segment456', 'user@example.com')
+        def delete(list_id, segment_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments/#{segment_id}/members/#{subscriber_hash(email)}"
+          client.delete(path, query: query, body: body, headers: headers)
+        end
+
+        # Iterate through all members in a segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @yield [Hash] Each segment member
+        # @example Iterate through segment members
+        #   segment_members.each('list123', 'segment456') do |member|
+        #     puts member[:email_address]
+        #   end
+        def each(list_id, segment_id, query: nil, body: nil, headers: nil, &block)
+          list_each_item(:members, list_id, segment_id, query: query, body: body, headers: headers, &block)
+        end
+      end
+
+      include APIs
+      extend APIs
+    end
+  end
+end

data/lib/mailchimp-api/resources/audience/segments.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Audience
+    # Provides methods for interacting with Mailchimp segments
+    # Segments allow you to group subscribers based on specific conditions
+    class Segments < Resource
+      # Module with endpoints for Segments APIs
+      module APIs
+        include Pagination::ListEachItemHelper
+
+        # List all segments for a specific list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing segments
+        # @example Get all segments for a list
+        #   segments.list('list123')
+        def list(list_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        # Create a new segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Segment attributes
+        # @option body [String] :name The name of the segment
+        # @option body [Array<Hash>] :conditions Segment conditions
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing the created segment
+        # @example Create a static segment
+        #   segments.create('list123', body: {
+        #     name: 'Premium Customers',
+        #     static_segment: ['user1@example.com', 'user2@example.com']
+        #   })
+        def create(list_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+
+        # Show details for a specific segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing segment details
+        # @example Get details for a segment
+        #   segments.show('list123', 'segment456')
+        def show(list_id, segment_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments/#{segment_id}"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        # Update a segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment to update
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Updated segment attributes
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing updated segment
+        # @example Update a segment name
+        #   segments.update('list123', 'segment456', body: {
+        #     name: 'Updated Segment Name'
+        #   })
+        def update(list_id, segment_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments/#{segment_id}"
+          client.patch(path, query: query, body: body, headers: headers)
+        end
+
+        # Delete a segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment to delete
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Boolean] True if successful
+        # @example Delete a segment
+        #   segments.delete('list123', 'segment456')
+        def delete(list_id, segment_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments/#{segment_id}"
+          client.delete(path, query: query, body: body, headers: headers)
+        end
+
+        # Batch add or remove members from a static segment
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param segment_id [String] The ID of the segment
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Members to add/remove
+        # @option body [Array<String>] :members_to_add Array of emails to add
+        # @option body [Array<String>] :members_to_remove Array of emails to remove
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing update status
+        # @example Add and remove members from a segment
+        #   segments.batch_add_or_remove_members('list123', 'segment456', body: {
+        #     members_to_add: ['new@example.com'],
+        #     members_to_remove: ['old@example.com']
+        #   })
+        def batch_add_or_remove_members(list_id, segment_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/segments/#{segment_id}"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+
+        # Iterate through all segments for a list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @yield [Hash] Each segment
+        # @example Iterate through segments
+        #   segments.each('list123') do |segment|
+        #     puts segment[:name]
+        #   end
+        def each(list_id, query: nil, body: nil, headers: nil, &block)
+          list_each_item(:segments, list_id, query: query, body: body, headers: headers, &block)
+        end
+      end
+
+      include APIs
+      extend APIs
+    end
+  end
+end

data/lib/mailchimp-api/resources/audience/utils/subscriber_hash.rb

@@ -4,8 +4,17 @@ require "digest"
 
 module MailchimpAPI
   module Audience
+    # Namespace for utils that are required for Audience APIs collection
+    # @api private
     module Utils
+      # Internal class for generating MD5 hashes of email addresses
+      # @api private
       class SubscriberHash
+        # Generates an MD5 hash of a lowercase email address
+        # @param email [String] Email address to hash
+        # @return [String] MD5 hash of the lowercase email
+        # @example
+        #   SubscriberHash.call("User@Example.com") # => "b58996c504c5638798eb6b511e6f49af"
         def self.call(email)
           Digest::MD5.hexdigest(email.downcase)
         end

data/lib/mailchimp-api/resources/audience/webhooks.rb

@@ -2,35 +2,98 @@
 
 module MailchimpAPI
   module Audience
+    # Provides methods for interacting with Mailchimp webhooks
+    # Webhooks allow you to receive notifications about events in your Mailchimp account
     class Webhooks < Resource
+      # Module with endpoints for Webhooks APIs
       module APIs
         include Pagination::ListEachItemHelper
 
+        # List all webhooks for a specific list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing webhooks
+        # @example Get all webhooks for a list
+        #   webhooks.list('list123')
         def list(list_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/webhooks"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Create a new webhook
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Webhook attributes
+        # @option body [String] :url The URL for the webhook
+        # @option body [Hash] :events Events to subscribe to
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing the created webhook
+        # @example Create a webhook for subscribe events
+        #   webhooks.create('list123', body: {
+        #     url: 'https://example.com/webhook',
+        #     events: { subscribe: true }
+        #   })
         def create(list_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/webhooks"
           client.post(path, query: query, body: body, headers: headers)
         end
 
+        # Show details for a specific webhook
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param webhook_id [String] The ID of the webhook
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing webhook details
+        # @example Get details for a webhook
+        #   webhooks.show('list123', 'webhook456')
         def show(list_id, webhook_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/webhooks/#{webhook_id}"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Delete a webhook
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param webhook_id [String] The ID of the webhook to delete
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Boolean] True if successful
+        # @example Delete a webhook
+        #   webhooks.delete('list123', 'webhook456')
         def delete(list_id, webhook_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/webhooks/#{webhook_id}"
           client.delete(path, query: query, body: body, headers: headers)
         end
 
+        # Update a webhook
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param webhook_id [String] The ID of the webhook to update
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Updated webhook attributes
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing updated webhook
+        # @example Update webhook events
+        #   webhooks.update('list123', 'webhook456', body: {
+        #     events: { subscribe: true, unsubscribe: true }
+        #   })
         def update(list_id, webhook_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/webhooks/#{webhook_id}"
           client.patch(path, query: query, body: body, headers: headers)
         end
 
+        # Iterate through all webhooks for a list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @yield [Hash] Each webhook
+        # @example Iterate through webhooks
+        #   webhooks.each('list123') do |webhook|
+        #     puts webhook[:url]
+        #   end
         def each(list_id, query: nil, body: nil, headers: nil, &block)
           list_each_item(:webhooks, list_id, query: query, body: body, headers: headers, &block)
         end