context.dev 2.1.0 → 2.3.0

data/lib/context_dev/models/monitor_list_response.rb

@@ -124,7 +124,17 @@ module ContextDev
         #   @return [ContextDev::Models::MonitorListResponse::Data::Webhook, nil]
         optional :webhook, -> { ContextDev::Models::MonitorListResponse::Data::Webhook }, nil?: true
 
-        # @!method initialize(id:, change_detection:, created_at:, mode:, name:, schedule:, status:, target:, updated_at:, baseline: nil, last_change_at: nil, last_error: nil, last_run_at: nil, next_run_at: nil, tags: nil, webhook: nil)
+        # @!attribute webhook_failure
+        #   Present while webhook deliveries are failing consecutively; null when deliveries
+        #   are healthy or no webhook is configured. Cleared on the next successful delivery
+        #   and when the webhook URL changes.
+        #
+        #   @return [ContextDev::Models::MonitorListResponse::Data::WebhookFailure, nil]
+        optional :webhook_failure,
+                 -> { ContextDev::Models::MonitorListResponse::Data::WebhookFailure },
+                 nil?: true
+
+        # @!method initialize(id:, change_detection:, created_at:, mode:, name:, schedule:, status:, target:, updated_at:, baseline: nil, last_change_at: nil, last_error: nil, last_run_at: nil, next_run_at: nil, tags: nil, webhook: nil, webhook_failure: nil)
         #   Some parameter documentations has been truncated, see
         #   {ContextDev::Models::MonitorListResponse::Data} for more details.
         #
@@ -162,6 +172,8 @@ module ContextDev
         #   @param tags [Array<String>] User-defined tags for grouping and filtering monitors and their changes.
         #
         #   @param webhook [ContextDev::Models::MonitorListResponse::Data::Webhook, nil]
+        #
+        #   @param webhook_failure [ContextDev::Models::MonitorListResponse::Data::WebhookFailure, nil] Present while webhook deliveries are failing consecutively; null when deliveries
 
         # Discriminated union describing how changes are detected.
         #
@@ -174,7 +186,7 @@ module ContextDev
           # Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
           variant :exact, -> { ContextDev::Models::MonitorListResponse::Data::ChangeDetection::Exact }
 
-          # Detect meaning-level changes to the extracted data, ignoring cosmetic or paraphrase-only differences. What is watched is determined by the extract target's `schema` and `instructions`.
+          # Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
           variant :semantic, -> { ContextDev::Models::MonitorListResponse::Data::ChangeDetection::Semantic }
 
           class Exact < ContextDev::Internal::Type::BaseModel
@@ -202,9 +214,9 @@ module ContextDev
             optional :confidence_threshold, Float
 
             # @!method initialize(confidence_threshold: nil, type: :semantic)
-            #   Detect meaning-level changes to the extracted data, ignoring cosmetic or
-            #   paraphrase-only differences. What is watched is determined by the extract
-            #   target's `schema` and `instructions`.
+            #   Detect meaning-level changes to tracked page content, ignoring cosmetic or
+            #   paraphrase-only differences. Which changes are meaningful is judged against the
+            #   extract target's `instructions` (and `schema`, when provided).
             #
             #   @param confidence_threshold [Float]
             #   @param type [Symbol, :semantic]
@@ -316,7 +328,7 @@ module ContextDev
           # Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
           variant :sitemap, -> { ContextDev::Models::MonitorListResponse::Data::Target::Sitemap }
 
-          # Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged against the monitor's instructions. The tracked page set is refreshed by a periodic re-discovery crawl.
+          # Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl.
           variant :extract, -> { ContextDev::Models::MonitorListResponse::Data::Target::Extract }
 
           class Page < ContextDev::Internal::Type::BaseModel
@@ -431,9 +443,14 @@ module ContextDev
             optional :max_pages, Integer
 
             # @!attribute schema
-            #   JSON Schema describing the data you care about. It guides which pages are
-            #   selected for tracking and gives the change judge context on what matters. If
-            #   omitted, a default summary + key-points schema is used.
+            #   JSON Schema describing the data you care about. It is used three ways: it guides
+            #   which pages are selected for tracking, it gives the change judge extra context
+            #   on which changes matter (alongside `instructions`), and it defines the shape of
+            #   the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+            #   about once a day). It is not a response format for changes: change events and
+            #   webhook payloads always contain diffs, summaries, and evidence excerpts — never
+            #   data in this schema's shape. If omitted, a default summary + key-points schema
+            #   is used.
             #
             #   @return [Hash{Symbol=>Object}, nil]
             optional :schema, ContextDev::Internal::Type::HashOf[ContextDev::Internal::Type::Unknown]
@@ -446,8 +463,8 @@ module ContextDev
             #   Watch the monitor-relevant pages of a site for meaningful changes. A crawl
             #   guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
             #   track; each run re-checks exactly those pages, and confirmed content changes are
-            #   judged against the monitor's instructions. The tracked page set is refreshed by
-            #   a periodic re-discovery crawl.
+            #   judged for relevance against the monitor's `instructions` (and `schema`, when
+            #   provided). The tracked page set is refreshed by a periodic re-discovery crawl.
             #
             #   @param instructions [String] Natural-language instructions guiding which pages and facts to track and which c
             #
@@ -459,7 +476,7 @@ module ContextDev
             #
             #   @param max_pages [Integer] Maximum number of pages to track.
             #
-            #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the data you care about. It guides which pages are select
+            #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the data you care about. It is used three ways: it guides
             #
             #   @param type [Symbol, :extract]
           end
@@ -600,11 +617,21 @@ module ContextDev
         # @see ContextDev::Models::MonitorListResponse::Data#webhook
         class Webhook < ContextDev::Internal::Type::BaseModel
           # @!attribute url
-          #   Webhook URL called when a change is detected.
+          #   Webhook URL events are delivered to.
           #
           #   @return [String]
           required :url, String
 
+          # @!attribute events
+          #   Events delivered to this endpoint. `change.detected` fires only when a run
+          #   detects a change; `run.completed` fires on every completed run — including runs
+          #   that detected no change — and embeds the change when one was detected. Defaults
+          #   to `["change.detected"]` when omitted.
+          #
+          #   @return [Array<Symbol, ContextDev::Models::MonitorListResponse::Data::Webhook::Event>, nil]
+          optional :events,
+                   -> { ContextDev::Internal::Type::ArrayOf[enum: ContextDev::Models::MonitorListResponse::Data::Webhook::Event] }
+
           response_only do
             # @!attribute secret
             #   Signing secret used to verify webhook authenticity. Each delivery includes an
@@ -617,13 +644,87 @@ module ContextDev
             optional :secret, String
           end
 
-          # @!method initialize(url:, secret: nil)
+          # @!method initialize(url:, events: nil, secret: nil)
           #   Some parameter documentations has been truncated, see
           #   {ContextDev::Models::MonitorListResponse::Data::Webhook} for more details.
           #
-          #   @param url [String] Webhook URL called when a change is detected.
+          #   @param url [String] Webhook URL events are delivered to.
+          #
+          #   @param events [Array<Symbol, ContextDev::Models::MonitorListResponse::Data::Webhook::Event>] Events delivered to this endpoint. `change.detected` fires only when a run detec
           #
           #   @param secret [String] Signing secret used to verify webhook authenticity. Each delivery includes an `X
+
+          module Event
+            extend ContextDev::Internal::Type::Enum
+
+            CHANGE_DETECTED = :"change.detected"
+            RUN_COMPLETED = :"run.completed"
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+
+        # @see ContextDev::Models::MonitorListResponse::Data#webhook_failure
+        class WebhookFailure < ContextDev::Internal::Type::BaseModel
+          # @!attribute consecutive_failures
+          #   Number of consecutive delivery attempts that did not succeed.
+          #
+          #   @return [Integer]
+          required :consecutive_failures, Integer
+
+          # @!attribute last_failed_at
+          #
+          #   @return [Time]
+          required :last_failed_at, Time
+
+          # @!attribute last_message
+          #   Human-readable description of the most recent failure.
+          #
+          #   @return [String]
+          required :last_message, String
+
+          # @!attribute last_status
+          #   Outcome of the most recent failed delivery. rejected means a non-2xx response;
+          #   failed means no HTTP response was received; skipped_unsafe_url means the URL
+          #   failed the public-endpoint safety check.
+          #
+          #   @return [Symbol, ContextDev::Models::MonitorListResponse::Data::WebhookFailure::LastStatus]
+          required :last_status,
+                   enum: -> { ContextDev::Models::MonitorListResponse::Data::WebhookFailure::LastStatus }
+
+          # @!method initialize(consecutive_failures:, last_failed_at:, last_message:, last_status:)
+          #   Some parameter documentations has been truncated, see
+          #   {ContextDev::Models::MonitorListResponse::Data::WebhookFailure} for more
+          #   details.
+          #
+          #   Present while webhook deliveries are failing consecutively; null when deliveries
+          #   are healthy or no webhook is configured. Cleared on the next successful delivery
+          #   and when the webhook URL changes.
+          #
+          #   @param consecutive_failures [Integer] Number of consecutive delivery attempts that did not succeed.
+          #
+          #   @param last_failed_at [Time]
+          #
+          #   @param last_message [String] Human-readable description of the most recent failure.
+          #
+          #   @param last_status [Symbol, ContextDev::Models::MonitorListResponse::Data::WebhookFailure::LastStatus] Outcome of the most recent failed delivery. rejected means a non-2xx response; f
+
+          # Outcome of the most recent failed delivery. rejected means a non-2xx response;
+          # failed means no HTTP response was received; skipped_unsafe_url means the URL
+          # failed the public-endpoint safety check.
+          #
+          # @see ContextDev::Models::MonitorListResponse::Data::WebhookFailure#last_status
+          module LastStatus
+            extend ContextDev::Internal::Type::Enum
+
+            REJECTED = :rejected
+            FAILED = :failed
+            SKIPPED_UNSAFE_URL = :skipped_unsafe_url
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
         end
       end
     end

data/lib/context_dev/models/monitor_list_runs_response.rb

@@ -106,7 +106,25 @@ module ContextDev
         #   @return [Time, nil]
         optional :started_at, Time, nil?: true
 
-        # @!method initialize(id:, baseline_created:, change_detected:, change_detection_type:, credits_charged:, monitor_id:, run_type:, status:, target_type:, change_id: nil, completed_at: nil, error: nil, skip_reason: nil, started_at: nil)
+        # @!attribute webhook_deliveries
+        #   All webhook deliveries attempted by this run — one per subscribed event that
+        #   fired. Omitted when no webhook was attempted, including runs created before
+        #   event selection was added.
+        #
+        #   @return [Array<ContextDev::Models::WebhookDelivery>, nil]
+        optional :webhook_deliveries, -> { ContextDev::Internal::Type::ArrayOf[ContextDev::WebhookDelivery] }
+
+        # @!attribute webhook_delivery
+        #   @deprecated
+        #
+        #   Deprecated: use `webhook_deliveries`, which records every attempt now that a run
+        #   can deliver multiple events. Omitted when no webhook was attempted, including
+        #   historical runs created before delivery tracking was added.
+        #
+        #   @return [ContextDev::Models::WebhookDelivery, nil]
+        optional :webhook_delivery, -> { ContextDev::WebhookDelivery }
+
+        # @!method initialize(id:, baseline_created:, change_detected:, change_detection_type:, credits_charged:, monitor_id:, run_type:, status:, target_type:, change_id: nil, completed_at: nil, error: nil, skip_reason: nil, started_at: nil, webhook_deliveries: nil, webhook_delivery: nil)
         #   Some parameter documentations has been truncated, see
         #   {ContextDev::Models::MonitorListRunsResponse::Data} for more details.
         #
@@ -137,6 +155,10 @@ module ContextDev
         #   @param skip_reason [Symbol, ContextDev::Models::MonitorListRunsResponse::Data::SkipReason, nil] Why a skipped run never executed; null unless status is `skipped`.
         #
         #   @param started_at [Time, nil]
+        #
+        #   @param webhook_deliveries [Array<ContextDev::Models::WebhookDelivery>] All webhook deliveries attempted by this run — one per subscribed event that fir
+        #
+        #   @param webhook_delivery [ContextDev::Models::WebhookDelivery] Deprecated: use `webhook_deliveries`, which records every attempt now that a run
 
         # @see ContextDev::Models::MonitorListRunsResponse::Data#change_detection_type
         module ChangeDetectionType

data/lib/context_dev/models/monitor_retrieve_change_response.rb

@@ -43,6 +43,12 @@ module ContextDev
       #   @return [String]
       required :summary, String
 
+      # @!attribute tags
+      #   User-defined tags for grouping and filtering monitors and their changes.
+      #
+      #   @return [Array<String>]
+      required :tags, ContextDev::Internal::Type::ArrayOf[String]
+
       # @!attribute target_type
       #
       #   @return [Symbol, ContextDev::Models::MonitorRetrieveChangeResponse::TargetType]
@@ -123,13 +129,7 @@ module ContextDev
       #   @return [Array<String>, nil]
       optional :removed_urls, ContextDev::Internal::Type::ArrayOf[String]
 
-      # @!attribute tags
-      #   User-defined tags for grouping and filtering monitors and their changes.
-      #
-      #   @return [Array<String>, nil]
-      optional :tags, ContextDev::Internal::Type::ArrayOf[String]
-
-      # @!method initialize(id:, change_detection_type:, detected_at:, mode:, monitor_id:, run_id:, summary:, target_type:, title:, url:, added_url_count: nil, added_urls: nil, after_text_excerpt: nil, before_text_excerpt: nil, confidence: nil, diff: nil, evidence: nil, importance: nil, matched_url_count: nil, matched_urls: nil, removed_url_count: nil, removed_urls: nil, tags: nil)
+      # @!method initialize(id:, change_detection_type:, detected_at:, mode:, monitor_id:, run_id:, summary:, tags:, target_type:, title:, url:, added_url_count: nil, added_urls: nil, after_text_excerpt: nil, before_text_excerpt: nil, confidence: nil, diff: nil, evidence: nil, importance: nil, matched_url_count: nil, matched_urls: nil, removed_url_count: nil, removed_urls: nil)
       #   Some parameter documentations has been truncated, see
       #   {ContextDev::Models::MonitorRetrieveChangeResponse} for more details.
       #
@@ -137,7 +137,7 @@ module ContextDev
       #   `change_detection_type` describe the change, and which optional fields are
       #   present depends on them (page: `diff` + excerpts; sitemap:
       #   `added_urls`/`removed_urls`; semantic:
-      #   `query`/`confidence`/`importance`/`evidence`/`matched_urls`).
+      #   `confidence`/`importance`/`evidence`/`matched_urls`).
       #
       #   @param id [String]
       #
@@ -153,6 +153,8 @@ module ContextDev
       #
       #   @param summary [String]
       #
+      #   @param tags [Array<String>] User-defined tags for grouping and filtering monitors and their changes.
+      #
       #   @param target_type [Symbol, ContextDev::Models::MonitorRetrieveChangeResponse::TargetType]
       #
       #   @param title [String]
@@ -182,8 +184,6 @@ module ContextDev
       #   @param removed_url_count [Integer]
       #
       #   @param removed_urls [Array<String>] At most 500 URLs are included; the corresponding count field is always exact.
-      #
-      #   @param tags [Array<String>] User-defined tags for grouping and filtering monitors and their changes.
 
       # @see ContextDev::Models::MonitorRetrieveChangeResponse#change_detection_type
       module ChangeDetectionType

data/lib/context_dev/models/monitor_retrieve_response.rb

@@ -103,7 +103,15 @@ module ContextDev
       #   @return [ContextDev::Models::MonitorRetrieveResponse::Webhook, nil]
       optional :webhook, -> { ContextDev::Models::MonitorRetrieveResponse::Webhook }, nil?: true
 
-      # @!method initialize(id:, change_detection:, created_at:, mode:, name:, schedule:, status:, target:, updated_at:, baseline: nil, last_change_at: nil, last_error: nil, last_run_at: nil, next_run_at: nil, tags: nil, webhook: nil)
+      # @!attribute webhook_failure
+      #   Present while webhook deliveries are failing consecutively; null when deliveries
+      #   are healthy or no webhook is configured. Cleared on the next successful delivery
+      #   and when the webhook URL changes.
+      #
+      #   @return [ContextDev::Models::MonitorRetrieveResponse::WebhookFailure, nil]
+      optional :webhook_failure, -> { ContextDev::Models::MonitorRetrieveResponse::WebhookFailure }, nil?: true
+
+      # @!method initialize(id:, change_detection:, created_at:, mode:, name:, schedule:, status:, target:, updated_at:, baseline: nil, last_change_at: nil, last_error: nil, last_run_at: nil, next_run_at: nil, tags: nil, webhook: nil, webhook_failure: nil)
       #   Some parameter documentations has been truncated, see
       #   {ContextDev::Models::MonitorRetrieveResponse} for more details.
       #
@@ -141,6 +149,8 @@ module ContextDev
       #   @param tags [Array<String>] User-defined tags for grouping and filtering monitors and their changes.
       #
       #   @param webhook [ContextDev::Models::MonitorRetrieveResponse::Webhook, nil]
+      #
+      #   @param webhook_failure [ContextDev::Models::MonitorRetrieveResponse::WebhookFailure, nil] Present while webhook deliveries are failing consecutively; null when deliveries
 
       # Discriminated union describing how changes are detected.
       #
@@ -153,7 +163,7 @@ module ContextDev
         # Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
         variant :exact, -> { ContextDev::Models::MonitorRetrieveResponse::ChangeDetection::Exact }
 
-        # Detect meaning-level changes to the extracted data, ignoring cosmetic or paraphrase-only differences. What is watched is determined by the extract target's `schema` and `instructions`.
+        # Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
         variant :semantic, -> { ContextDev::Models::MonitorRetrieveResponse::ChangeDetection::Semantic }
 
         class Exact < ContextDev::Internal::Type::BaseModel
@@ -181,9 +191,9 @@ module ContextDev
           optional :confidence_threshold, Float
 
           # @!method initialize(confidence_threshold: nil, type: :semantic)
-          #   Detect meaning-level changes to the extracted data, ignoring cosmetic or
-          #   paraphrase-only differences. What is watched is determined by the extract
-          #   target's `schema` and `instructions`.
+          #   Detect meaning-level changes to tracked page content, ignoring cosmetic or
+          #   paraphrase-only differences. Which changes are meaningful is judged against the
+          #   extract target's `instructions` (and `schema`, when provided).
           #
           #   @param confidence_threshold [Float]
           #   @param type [Symbol, :semantic]
@@ -295,7 +305,7 @@ module ContextDev
         # Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
         variant :sitemap, -> { ContextDev::Models::MonitorRetrieveResponse::Target::Sitemap }
 
-        # Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged against the monitor's instructions. The tracked page set is refreshed by a periodic re-discovery crawl.
+        # Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl.
         variant :extract, -> { ContextDev::Models::MonitorRetrieveResponse::Target::Extract }
 
         class Page < ContextDev::Internal::Type::BaseModel
@@ -410,9 +420,14 @@ module ContextDev
           optional :max_pages, Integer
 
           # @!attribute schema
-          #   JSON Schema describing the data you care about. It guides which pages are
-          #   selected for tracking and gives the change judge context on what matters. If
-          #   omitted, a default summary + key-points schema is used.
+          #   JSON Schema describing the data you care about. It is used three ways: it guides
+          #   which pages are selected for tracking, it gives the change judge extra context
+          #   on which changes matter (alongside `instructions`), and it defines the shape of
+          #   the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+          #   about once a day). It is not a response format for changes: change events and
+          #   webhook payloads always contain diffs, summaries, and evidence excerpts — never
+          #   data in this schema's shape. If omitted, a default summary + key-points schema
+          #   is used.
           #
           #   @return [Hash{Symbol=>Object}, nil]
           optional :schema, ContextDev::Internal::Type::HashOf[ContextDev::Internal::Type::Unknown]
@@ -424,8 +439,8 @@ module ContextDev
           #   Watch the monitor-relevant pages of a site for meaningful changes. A crawl
           #   guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
           #   track; each run re-checks exactly those pages, and confirmed content changes are
-          #   judged against the monitor's instructions. The tracked page set is refreshed by
-          #   a periodic re-discovery crawl.
+          #   judged for relevance against the monitor's `instructions` (and `schema`, when
+          #   provided). The tracked page set is refreshed by a periodic re-discovery crawl.
           #
           #   @param instructions [String] Natural-language instructions guiding which pages and facts to track and which c
           #
@@ -437,7 +452,7 @@ module ContextDev
           #
           #   @param max_pages [Integer] Maximum number of pages to track.
           #
-          #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the data you care about. It guides which pages are select
+          #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the data you care about. It is used three ways: it guides
           #
           #   @param type [Symbol, :extract]
         end
@@ -578,11 +593,21 @@ module ContextDev
       # @see ContextDev::Models::MonitorRetrieveResponse#webhook
       class Webhook < ContextDev::Internal::Type::BaseModel
         # @!attribute url
-        #   Webhook URL called when a change is detected.
+        #   Webhook URL events are delivered to.
         #
         #   @return [String]
         required :url, String
 
+        # @!attribute events
+        #   Events delivered to this endpoint. `change.detected` fires only when a run
+        #   detects a change; `run.completed` fires on every completed run — including runs
+        #   that detected no change — and embeds the change when one was detected. Defaults
+        #   to `["change.detected"]` when omitted.
+        #
+        #   @return [Array<Symbol, ContextDev::Models::MonitorRetrieveResponse::Webhook::Event>, nil]
+        optional :events,
+                 -> { ContextDev::Internal::Type::ArrayOf[enum: ContextDev::Models::MonitorRetrieveResponse::Webhook::Event] }
+
         response_only do
           # @!attribute secret
           #   Signing secret used to verify webhook authenticity. Each delivery includes an
@@ -595,13 +620,86 @@ module ContextDev
           optional :secret, String
         end
 
-        # @!method initialize(url:, secret: nil)
+        # @!method initialize(url:, events: nil, secret: nil)
         #   Some parameter documentations has been truncated, see
         #   {ContextDev::Models::MonitorRetrieveResponse::Webhook} for more details.
         #
-        #   @param url [String] Webhook URL called when a change is detected.
+        #   @param url [String] Webhook URL events are delivered to.
+        #
+        #   @param events [Array<Symbol, ContextDev::Models::MonitorRetrieveResponse::Webhook::Event>] Events delivered to this endpoint. `change.detected` fires only when a run detec
         #
         #   @param secret [String] Signing secret used to verify webhook authenticity. Each delivery includes an `X
+
+        module Event
+          extend ContextDev::Internal::Type::Enum
+
+          CHANGE_DETECTED = :"change.detected"
+          RUN_COMPLETED = :"run.completed"
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      # @see ContextDev::Models::MonitorRetrieveResponse#webhook_failure
+      class WebhookFailure < ContextDev::Internal::Type::BaseModel
+        # @!attribute consecutive_failures
+        #   Number of consecutive delivery attempts that did not succeed.
+        #
+        #   @return [Integer]
+        required :consecutive_failures, Integer
+
+        # @!attribute last_failed_at
+        #
+        #   @return [Time]
+        required :last_failed_at, Time
+
+        # @!attribute last_message
+        #   Human-readable description of the most recent failure.
+        #
+        #   @return [String]
+        required :last_message, String
+
+        # @!attribute last_status
+        #   Outcome of the most recent failed delivery. rejected means a non-2xx response;
+        #   failed means no HTTP response was received; skipped_unsafe_url means the URL
+        #   failed the public-endpoint safety check.
+        #
+        #   @return [Symbol, ContextDev::Models::MonitorRetrieveResponse::WebhookFailure::LastStatus]
+        required :last_status,
+                 enum: -> { ContextDev::Models::MonitorRetrieveResponse::WebhookFailure::LastStatus }
+
+        # @!method initialize(consecutive_failures:, last_failed_at:, last_message:, last_status:)
+        #   Some parameter documentations has been truncated, see
+        #   {ContextDev::Models::MonitorRetrieveResponse::WebhookFailure} for more details.
+        #
+        #   Present while webhook deliveries are failing consecutively; null when deliveries
+        #   are healthy or no webhook is configured. Cleared on the next successful delivery
+        #   and when the webhook URL changes.
+        #
+        #   @param consecutive_failures [Integer] Number of consecutive delivery attempts that did not succeed.
+        #
+        #   @param last_failed_at [Time]
+        #
+        #   @param last_message [String] Human-readable description of the most recent failure.
+        #
+        #   @param last_status [Symbol, ContextDev::Models::MonitorRetrieveResponse::WebhookFailure::LastStatus] Outcome of the most recent failed delivery. rejected means a non-2xx response; f
+
+        # Outcome of the most recent failed delivery. rejected means a non-2xx response;
+        # failed means no HTTP response was received; skipped_unsafe_url means the URL
+        # failed the public-endpoint safety check.
+        #
+        # @see ContextDev::Models::MonitorRetrieveResponse::WebhookFailure#last_status
+        module LastStatus
+          extend ContextDev::Internal::Type::Enum
+
+          REJECTED = :rejected
+          FAILED = :failed
+          SKIPPED_UNSAFE_URL = :skipped_unsafe_url
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
       end
     end
   end

data/lib/context_dev/models/monitor_update_params.rb

@@ -85,7 +85,7 @@ module ContextDev
         # Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
         variant :exact, -> { ContextDev::MonitorUpdateParams::ChangeDetection::Exact }
 
-        # Detect meaning-level changes to the extracted data, ignoring cosmetic or paraphrase-only differences. What is watched is determined by the extract target's `schema` and `instructions`.
+        # Detect meaning-level changes to tracked page content, ignoring cosmetic or paraphrase-only differences. Which changes are meaningful is judged against the extract target's `instructions` (and `schema`, when provided).
         variant :semantic, -> { ContextDev::MonitorUpdateParams::ChangeDetection::Semantic }
 
         class Exact < ContextDev::Internal::Type::BaseModel
@@ -113,9 +113,9 @@ module ContextDev
           optional :confidence_threshold, Float
 
           # @!method initialize(confidence_threshold: nil, type: :semantic)
-          #   Detect meaning-level changes to the extracted data, ignoring cosmetic or
-          #   paraphrase-only differences. What is watched is determined by the extract
-          #   target's `schema` and `instructions`.
+          #   Detect meaning-level changes to tracked page content, ignoring cosmetic or
+          #   paraphrase-only differences. Which changes are meaningful is judged against the
+          #   extract target's `instructions` (and `schema`, when provided).
           #
           #   @param confidence_threshold [Float]
           #   @param type [Symbol, :semantic]
@@ -203,7 +203,7 @@ module ContextDev
         # Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
         variant :sitemap, -> { ContextDev::MonitorUpdateParams::Target::Sitemap }
 
-        # Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged against the monitor's instructions. The tracked page set is refreshed by a periodic re-discovery crawl.
+        # Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl.
         variant :extract, -> { ContextDev::MonitorUpdateParams::Target::Extract }
 
         class Page < ContextDev::Internal::Type::BaseModel
@@ -318,9 +318,14 @@ module ContextDev
           optional :max_pages, Integer
 
           # @!attribute schema
-          #   JSON Schema describing the data you care about. It guides which pages are
-          #   selected for tracking and gives the change judge context on what matters. If
-          #   omitted, a default summary + key-points schema is used.
+          #   JSON Schema describing the data you care about. It is used three ways: it guides
+          #   which pages are selected for tracking, it gives the change judge extra context
+          #   on which changes matter (alongside `instructions`), and it defines the shape of
+          #   the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+          #   about once a day). It is not a response format for changes: change events and
+          #   webhook payloads always contain diffs, summaries, and evidence excerpts — never
+          #   data in this schema's shape. If omitted, a default summary + key-points schema
+          #   is used.
           #
           #   @return [Hash{Symbol=>Object}, nil]
           optional :schema, ContextDev::Internal::Type::HashOf[ContextDev::Internal::Type::Unknown]
@@ -332,8 +337,8 @@ module ContextDev
           #   Watch the monitor-relevant pages of a site for meaningful changes. A crawl
           #   guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
           #   track; each run re-checks exactly those pages, and confirmed content changes are
-          #   judged against the monitor's instructions. The tracked page set is refreshed by
-          #   a periodic re-discovery crawl.
+          #   judged for relevance against the monitor's `instructions` (and `schema`, when
+          #   provided). The tracked page set is refreshed by a periodic re-discovery crawl.
           #
           #   @param instructions [String] Natural-language instructions guiding which pages and facts to track and which c
           #
@@ -345,7 +350,7 @@ module ContextDev
           #
           #   @param max_pages [Integer] Maximum number of pages to track.
           #
-          #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the data you care about. It guides which pages are select
+          #   @param schema [Hash{Symbol=>Object}] JSON Schema describing the data you care about. It is used three ways: it guides
           #
           #   @param type [Symbol, :extract]
         end
@@ -356,15 +361,40 @@ module ContextDev
 
       class Webhook < ContextDev::Internal::Type::BaseModel
         # @!attribute url
-        #   Webhook URL called when a change is detected.
+        #   Webhook URL events are delivered to.
         #
         #   @return [String]
         required :url, String
 
-        # @!method initialize(url:)
+        # @!attribute events
+        #   Events delivered to this endpoint. `change.detected` fires only when a run
+        #   detects a change; `run.completed` fires on every completed run — including runs
+        #   that detected no change — and embeds the change when one was detected. Defaults
+        #   to `["change.detected"]` when omitted.
+        #
+        #   @return [Array<Symbol, ContextDev::Models::MonitorUpdateParams::Webhook::Event>, nil]
+        optional :events,
+                 -> { ContextDev::Internal::Type::ArrayOf[enum: ContextDev::MonitorUpdateParams::Webhook::Event] }
+
+        # @!method initialize(url:, events: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {ContextDev::Models::MonitorUpdateParams::Webhook} for more details.
+        #
         #   Set to null to remove the webhook.
         #
-        #   @param url [String] Webhook URL called when a change is detected.
+        #   @param url [String] Webhook URL events are delivered to.
+        #
+        #   @param events [Array<Symbol, ContextDev::Models::MonitorUpdateParams::Webhook::Event>] Events delivered to this endpoint. `change.detected` fires only when a run detec
+
+        module Event
+          extend ContextDev::Internal::Type::Enum
+
+          CHANGE_DETECTED = :"change.detected"
+          RUN_COMPLETED = :"run.completed"
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
       end
     end
   end