@sentdm/sentdm 0.33.0 → 0.35.0

package/src/resources/webhooks.ts

@@ -8,7 +8,11 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 /**
- * Configure webhook endpoints for real-time event delivery
+ * Delivery reports and inbound messages, pushed to you.
+ *
+ * Subscribe an endpoint to the event types you care about — `GET /v3/webhooks/event-types` lists them — and we POST each one as it happens, retrying on failure. Polling `GET /v3/messages/{id}` works and does not scale.
+ *
+ * **Verify the signature.** Every delivery is signed with your endpoint's secret; an unverified endpoint is one anybody can post to. `rotate-secret` replaces it, `test` sends a specimen event, and `GET /v3/webhooks/{id}/events` shows what we tried to deliver and what your endpoint answered — which is the first place to look when something appears to be missing.
  */
 export class Webhooks extends APIResource {
   /**
@@ -16,10 +20,10 @@ export class Webhooks extends APIResource {
    *
    * @example
    * ```ts
-   * const apiResponseWebhook = await client.webhooks.create();
+   * const webhook = await client.webhooks.create();
    * ```
    */
-  create(params: WebhookCreateParams, options?: RequestOptions): APIPromise<APIResponseWebhook> {
+  create(params: WebhookCreateParams, options?: RequestOptions): APIPromise<WebhookCreateResponse> {
     const { 'Idempotency-Key': idempotencyKey, 'x-profile-id': xProfileID, ...body } = params;
     return this._client.post('/v3/webhooks', {
       body,
@@ -39,7 +43,7 @@ export class Webhooks extends APIResource {
    *
    * @example
    * ```ts
-   * const apiResponseWebhook = await client.webhooks.retrieve(
+   * const webhook = await client.webhooks.retrieve(
    *   'd4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8',
    * );
    * ```
@@ -48,7 +52,7 @@ export class Webhooks extends APIResource {
     id: string,
     params: WebhookRetrieveParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<APIResponseWebhook> {
+  ): APIPromise<WebhookRetrieveResponse> {
     const { 'x-profile-id': xProfileID } = params ?? {};
     return this._client.get(path`/v3/webhooks/${id}`, {
       ...options,
@@ -64,12 +68,16 @@ export class Webhooks extends APIResource {
    *
    * @example
    * ```ts
-   * const apiResponseWebhook = await client.webhooks.update(
+   * const webhook = await client.webhooks.update(
    *   'd4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8',
    * );
    * ```
    */
-  update(id: string, params: WebhookUpdateParams, options?: RequestOptions): APIPromise<APIResponseWebhook> {
+  update(
+    id: string,
+    params: WebhookUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<WebhookUpdateResponse> {
     const { 'Idempotency-Key': idempotencyKey, 'x-profile-id': xProfileID, ...body } = params;
     return this._client.put(path`/v3/webhooks/${id}`, {
       body,
@@ -241,17 +249,16 @@ export class Webhooks extends APIResource {
    *
    * @example
    * ```ts
-   * const apiResponseWebhook =
-   *   await client.webhooks.toggleStatus(
-   *     'd4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8',
-   *   );
+   * const response = await client.webhooks.toggleStatus(
+   *   'd4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8',
+   * );
    * ```
    */
   toggleStatus(
     id: string,
     params: WebhookToggleStatusParams,
     options?: RequestOptions,
-  ): APIPromise<APIResponseWebhook> {
+  ): APIPromise<WebhookToggleStatusResponse> {
     const { 'Idempotency-Key': idempotencyKey, 'x-profile-id': xProfileID, ...body } = params;
     return this._client.patch(path`/v3/webhooks/${id}/toggle-status`, {
       body,
@@ -268,197 +275,279 @@ export class Webhooks extends APIResource {
 }
 
 /**
- * Request and response metadata
+ * The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+ * this shape and varies only in Payload.
  */
-export interface APIMeta {
+export interface InboundMessageEvent {
   /**
-   * Unique identifier for this request (for tracing and support)
+   * The specific event within the family, for example message.delivered or
+   * message.received. Absent on events that have no subtype, so treat it as
+   * optional.
    */
-  request_id?: string;
+  event?: string | null;
 
   /**
-   * Server timestamp when the response was generated
+   * The event family, for example message or templates. Route on this first, then on
+   * event for the specific change.
    */
-  timestamp?: string;
+  field?: string;
 
   /**
-   * API version used for this request
+   * Body of a message.received event. Delivered when a contact messages one of your
+   * numbers.
    */
-  version?: string;
-}
+  payload?: InboundMessageEventPayload | null;
 
-/**
- * Standard API response envelope for all v3 endpoints
- */
-export interface APIResponseWebhook {
   /**
-   * The response data (null if error)
+   * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+   * time, not the time the underlying change happened. Use the timestamp inside the
+   * payload for the latter.
    */
-  data?: WebhookResponse | null;
+  timestamp?: string;
+}
 
+/**
+ * Body of a message.received event. Delivered when a contact messages one of your
+ * numbers.
+ */
+export interface InboundMessageEventPayload {
   /**
-   * Error information
+   * The account the message belongs to.
    */
-  error?: ErrorDetail | null;
+  account_id?: string;
 
   /**
-   * Request and response metadata
+   * The channel the message arrived on, for example sms or whatsapp.
    */
-  meta?: APIMeta;
+  channel?: string;
 
   /**
-   * Indicates whether the request was successful
+   * The contact's number in E.164 format, meaning the number the message came from.
    */
-  success?: boolean;
-}
+  inbound_number?: string;
 
-/**
- * Error information
- */
-export interface ErrorDetail {
   /**
-   * Machine-readable error code (e.g., "RESOURCE_001")
+   * The inbound message.
    */
-  code?: string;
+  message_id?: string;
 
   /**
-   * Additional validation error details (field-level errors)
+   * Your number in E.164 format, meaning the number the message was addressed to.
    */
-  details?: { [key: string]: Array<string> } | null;
+  outbound_number?: string;
 
   /**
-   * URL to documentation about this error
+   * When the message was received, in UTC (yyyy-MM-ddTHH:mm:ssZ).
    */
-  doc_url?: string | null;
+  received_at?: string;
 
   /**
-   * Human-readable error message
+   * The message body. Sent as null when the inbound message carried no text, for
+   * example a media-only message. The field is always present, so read it and check
+   * for null rather than checking whether the key exists.
    */
-  message?: string;
-}
+  text?: string | null;
 
-export interface MutationRequest {
   /**
-   * Sandbox flag - when true, the operation is simulated without side effects Useful
-   * for testing integrations without actual execution
+   * When the message was received, in UTC (yyyy-MM-ddTHH:mm:ssZ). Same value as
+   * ReceivedAt, kept for envelope consistency with outbound events.
    */
-  sandbox?: boolean;
+  updated_at?: string;
 }
 
 /**
- * Pagination metadata for list responses
+ * The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+ * this shape and varies only in Payload.
  */
-export interface PaginationMeta {
+export interface MessageEvent {
   /**
-   * Cursor-based pagination pointers
+   * The specific event within the family, for example message.delivered or
+   * message.received. Absent on events that have no subtype, so treat it as
+   * optional.
    */
-  cursors?: PaginationMeta.Cursors | null;
+  event?: string | null;
 
   /**
-   * Whether there are more pages after this one
+   * The event family, for example message or templates. Route on this first, then on
+   * event for the specific change.
    */
-  has_more?: boolean;
+  field?: string;
 
   /**
-   * Current page number (1-indexed)
+   * Body of an outbound message lifecycle event. Delivered once per status change,
+   * so a single message produces several of these as it moves toward a terminal
+   * status.
    */
-  page?: number;
+  payload?: MessageEventPayload | null;
 
   /**
-   * Number of items per page
+   * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+   * time, not the time the underlying change happened. Use the timestamp inside the
+   * payload for the latter.
    */
-  page_size?: number;
+  timestamp?: string;
+}
 
+/**
+ * Body of an outbound message lifecycle event. Delivered once per status change,
+ * so a single message produces several of these as it moves toward a terminal
+ * status.
+ */
+export interface MessageEventPayload {
   /**
-   * Total number of items across all pages
+   * The account the message belongs to.
    */
-  total_count?: number;
+  account_id?: string;
 
   /**
-   * Total number of pages
+   * The agent attributed to the send, when the send was attributed to one.
    */
-  total_pages?: number;
-}
+  agent_id?: string | null;
 
-export namespace PaginationMeta {
   /**
-   * Cursor-based pagination pointers
+   * The channel the message went out on, for example sms or whatsapp. A message that
+   * falls back to another channel reports the channel actually used.
    */
-  export interface Cursors {
-    /**
-     * Cursor to fetch the next page
-     */
-    after?: string | null;
-
-    /**
-     * Cursor to fetch the previous page
-     */
-    before?: string | null;
-  }
-}
+  channel?: string;
 
-export interface WebhookEventType {
-  description?: string | null;
+  /**
+   * The message this event describes. Stable across every event in the message's
+   * lifecycle, so use it to correlate them.
+   */
+  message_id?: string;
 
-  display_name?: string;
+  /**
+   * The status the message just reached, for example SENT, DELIVERED, or FAILED.
+   * Sent means dispatched and delivered means confirmed, so treat them as distinct
+   * outcomes.
+   */
+  message_status?: string;
 
-  event_type?: string | null;
+  /**
+   * The recipient's number in E.164 format.
+   */
+  outbound_number?: string;
 
-  is_active?: boolean;
+  /**
+   * The template the message was sent from, when it was sent from one.
+   */
+  template_id?: string | null;
 
-  name?: string;
+  /**
+   * Name of the template the message was sent from. Omitted when the message wasn't
+   * template-based.
+   */
+  template_name?: string | null;
 
-  sub_types?: Array<WebhookEventType> | null;
+  /**
+   * When the message reached MessageStatus, in UTC (yyyy-MM-ddTHH:mm:ssZ).
+   */
+  updated_at?: string;
 }
 
-export interface WebhookResponse {
-  id?: string;
-
-  consecutive_failures?: number;
+/**
+ * The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+ * this shape and varies only in Payload.
+ */
+export interface TemplateEvent {
+  /**
+   * The specific event within the family, for example message.delivered or
+   * message.received. Absent on events that have no subtype, so treat it as
+   * optional.
+   */
+  event?: string | null;
 
-  created_at?: string;
+  /**
+   * The event family, for example message or templates. Route on this first, then on
+   * event for the specific change.
+   */
+  field?: string;
 
-  display_name?: string;
+  /**
+   * Body of a template status event. Delivered when a template's review outcome
+   * changes, so you can react without polling.
+   */
+  payload?: TemplateEventPayload | null;
 
-  endpoint_url?: string;
+  /**
+   * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+   * time, not the time the underlying change happened. Use the timestamp inside the
+   * payload for the latter.
+   */
+  timestamp?: string;
+}
 
-  event_filters?: { [key: string]: Array<string> } | null;
+/**
+ * Body of a template status event. Delivered when a template's review outcome
+ * changes, so you can react without polling.
+ */
+export interface TemplateEventPayload {
+  /**
+   * The account the template belongs to.
+   */
+  account_id?: string;
 
-  event_types?: Array<string>;
+  /**
+   * The template's category, for example UTILITY, MARKETING, or AUTHENTICATION.
+   */
+  category?: string;
 
-  is_active?: boolean;
+  /**
+   * The channel the template applies to.
+   */
+  channel?: string;
 
-  last_delivery_attempt_at?: string | null;
+  /**
+   * The template's language code, for example en_US.
+   */
+  language?: string;
 
-  last_successful_delivery_at?: string | null;
+  /**
+   * Why the template reached Status, when a reason was given. Populated on a
+   * rejection.
+   */
+  reason?: string | null;
 
-  retry_count?: number;
+  /**
+   * The review status the template just reached, for example APPROVED or REJECTED.
+   */
+  status?: string;
 
-  signing_secret?: string | null;
+  /**
+   * The template in Sent.
+   */
+  template_id?: string;
 
-  timeout_seconds?: number;
+  /**
+   * The template's display name.
+   */
+  template_name?: string;
 
-  updated_at?: string | null;
+  /**
+   * The template's identifier with Meta, assigned when the template is submitted for
+   * review.
+   */
+  whatsapp_template_id?: string;
 }
 
 /**
  * Standard API response envelope for all v3 endpoints
  */
-export interface WebhookListResponse {
+export interface WebhookCreateResponse {
   /**
    * The response data (null if error)
    */
-  data?: WebhookListResponse.Data | null;
+  data?: WebhookCreateResponse.Data | null;
 
   /**
    * Error information
    */
-  error?: ErrorDetail | null;
+  error?: WebhookCreateResponse.Error | null;
 
   /**
    * Request and response metadata
    */
-  meta?: APIMeta;
+  meta?: WebhookCreateResponse.Meta;
 
   /**
    * Indicates whether the request was successful
@@ -466,72 +555,110 @@ export interface WebhookListResponse {
   success?: boolean;
 }
 
-export namespace WebhookListResponse {
+export namespace WebhookCreateResponse {
   /**
    * The response data (null if error)
    */
   export interface Data {
+    id?: string;
+
+    consecutive_failures?: number;
+
+    created_at?: string;
+
     /**
-     * Pagination metadata for list responses
+     * Which customer owns this — the key's own, or the profile named in x-profile-id.
+     * Says whose resource this is, which the resource's own id does not.
      */
-    pagination?: WebhooksAPI.PaginationMeta;
+    customer_id?: string;
 
-    webhooks?: Array<WebhooksAPI.WebhookResponse>;
-  }
-}
+    display_name?: string;
 
-/**
- * Standard API response envelope for all v3 endpoints
- */
-export interface WebhookListEventTypesResponse {
-  /**
-   * The response data (null if error)
-   */
-  data?: WebhookListEventTypesResponse.Data | null;
+    endpoint_url?: string;
+
+    event_filters?: { [key: string]: Array<string> } | null;
+
+    event_types?: Array<string>;
+
+    is_active?: boolean;
+
+    last_delivery_attempt_at?: string | null;
+
+    last_successful_delivery_at?: string | null;
+
+    retry_count?: number;
+
+    signing_secret?: string | null;
+
+    timeout_seconds?: number;
+
+    updated_at?: string | null;
+  }
 
   /**
    * Error information
    */
-  error?: ErrorDetail | null;
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
 
   /**
    * Request and response metadata
    */
-  meta?: APIMeta;
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
 
-  /**
-   * Indicates whether the request was successful
-   */
-  success?: boolean;
-}
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
 
-export namespace WebhookListEventTypesResponse {
-  /**
-   * The response data (null if error)
-   */
-  export interface Data {
-    event_types?: Array<WebhooksAPI.WebhookEventType>;
+    /**
+     * API version used for this request
+     */
+    version?: string;
   }
 }
 
 /**
  * Standard API response envelope for all v3 endpoints
  */
-export interface WebhookListEventsResponse {
+export interface WebhookRetrieveResponse {
   /**
    * The response data (null if error)
    */
-  data?: WebhookListEventsResponse.Data | null;
+  data?: WebhookRetrieveResponse.Data | null;
 
   /**
    * Error information
    */
-  error?: ErrorDetail | null;
+  error?: WebhookRetrieveResponse.Error | null;
 
   /**
    * Request and response metadata
    */
-  meta?: APIMeta;
+  meta?: WebhookRetrieveResponse.Meta;
 
   /**
    * Indicates whether the request was successful
@@ -539,64 +666,110 @@ export interface WebhookListEventsResponse {
   success?: boolean;
 }
 
-export namespace WebhookListEventsResponse {
+export namespace WebhookRetrieveResponse {
   /**
    * The response data (null if error)
    */
   export interface Data {
-    events?: Array<Data.Event>;
+    id?: string;
+
+    consecutive_failures?: number;
+
+    created_at?: string;
 
     /**
-     * Pagination metadata for list responses
+     * Which customer owns this — the key's own, or the profile named in x-profile-id.
+     * Says whose resource this is, which the resource's own id does not.
      */
-    pagination?: WebhooksAPI.PaginationMeta;
-  }
+    customer_id?: string;
 
-  export namespace Data {
-    export interface Event {
-      id?: string;
+    display_name?: string;
 
-      created_at?: string;
+    endpoint_url?: string;
 
-      delivery_attempts?: number;
+    event_filters?: { [key: string]: Array<string> } | null;
 
-      delivery_status?: string;
+    event_types?: Array<string>;
 
-      error_message?: string | null;
+    is_active?: boolean;
 
-      event_data?: unknown;
+    last_delivery_attempt_at?: string | null;
 
-      event_type?: string;
+    last_successful_delivery_at?: string | null;
 
-      http_status_code?: number | null;
+    retry_count?: number;
 
-      processing_completed_at?: string | null;
+    signing_secret?: string | null;
 
-      processing_started_at?: string | null;
+    timeout_seconds?: number;
 
-      response_body?: string | null;
-    }
+    updated_at?: string | null;
+  }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
   }
 }
 
 /**
  * Standard API response envelope for all v3 endpoints
  */
-export interface WebhookRotateSecretResponse {
+export interface WebhookUpdateResponse {
   /**
    * The response data (null if error)
    */
-  data?: WebhookRotateSecretResponse.Data | null;
+  data?: WebhookUpdateResponse.Data | null;
 
   /**
    * Error information
    */
-  error?: ErrorDetail | null;
+  error?: WebhookUpdateResponse.Error | null;
 
   /**
    * Request and response metadata
    */
-  meta?: APIMeta;
+  meta?: WebhookUpdateResponse.Meta;
 
   /**
    * Indicates whether the request was successful
@@ -604,33 +777,110 @@ export interface WebhookRotateSecretResponse {
   success?: boolean;
 }
 
-export namespace WebhookRotateSecretResponse {
+export namespace WebhookUpdateResponse {
   /**
    * The response data (null if error)
    */
   export interface Data {
-    signing_secret?: string;
+    id?: string;
+
+    consecutive_failures?: number;
+
+    created_at?: string;
+
+    /**
+     * Which customer owns this — the key's own, or the profile named in x-profile-id.
+     * Says whose resource this is, which the resource's own id does not.
+     */
+    customer_id?: string;
+
+    display_name?: string;
+
+    endpoint_url?: string;
+
+    event_filters?: { [key: string]: Array<string> } | null;
+
+    event_types?: Array<string>;
+
+    is_active?: boolean;
+
+    last_delivery_attempt_at?: string | null;
+
+    last_successful_delivery_at?: string | null;
+
+    retry_count?: number;
+
+    signing_secret?: string | null;
+
+    timeout_seconds?: number;
+
+    updated_at?: string | null;
+  }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
   }
 }
 
 /**
  * Standard API response envelope for all v3 endpoints
  */
-export interface WebhookTestResponse {
+export interface WebhookListResponse {
   /**
-   * The response data (null if error)
+   * A paginated list of webhooks.
    */
-  data?: WebhookTestResponse.Data | null;
+  data?: WebhookListResponse.Data | null;
 
   /**
    * Error information
    */
-  error?: ErrorDetail | null;
+  error?: WebhookListResponse.Error | null;
 
   /**
    * Request and response metadata
    */
-  meta?: APIMeta;
+  meta?: WebhookListResponse.Meta;
 
   /**
    * Indicates whether the request was successful
@@ -638,15 +888,753 @@ export interface WebhookTestResponse {
   success?: boolean;
 }
 
-export namespace WebhookTestResponse {
+export namespace WebhookListResponse {
   /**
-   * The response data (null if error)
+   * A paginated list of webhooks.
    */
   export interface Data {
-    message?: string;
-
+    /**
+     * Pagination metadata for list responses
+     */
+    pagination?: Data.Pagination;
+
+    /**
+     * The webhooks on this page.
+     */
+    webhooks?: Array<Data.Webhook>;
+  }
+
+  export namespace Data {
+    /**
+     * Pagination metadata for list responses
+     */
+    export interface Pagination {
+      /**
+       * @deprecated Cursor-based pagination. Never populated — see Cursors.
+       */
+      cursors?: Pagination.Cursors | null;
+
+      /**
+       * Whether there are more pages after this one
+       */
+      has_more?: boolean;
+
+      /**
+       * Current page number (1-indexed)
+       */
+      page?: number;
+
+      /**
+       * Number of items per page
+       */
+      page_size?: number;
+
+      /**
+       * Total number of items across all pages
+       */
+      total_count?: number;
+
+      /**
+       * Total number of pages
+       */
+      total_pages?: number;
+    }
+
+    export namespace Pagination {
+      /**
+       * @deprecated Cursor-based pagination. Never populated — see Cursors.
+       */
+      export interface Cursors {
+        /**
+         * Cursor to fetch the next page.
+         */
+        after?: string | null;
+
+        /**
+         * Cursor to fetch the previous page.
+         */
+        before?: string | null;
+      }
+    }
+
+    export interface Webhook {
+      id?: string;
+
+      consecutive_failures?: number;
+
+      created_at?: string;
+
+      /**
+       * Which customer owns this — the key's own, or the profile named in x-profile-id.
+       * Says whose resource this is, which the resource's own id does not.
+       */
+      customer_id?: string;
+
+      display_name?: string;
+
+      endpoint_url?: string;
+
+      event_filters?: { [key: string]: Array<string> } | null;
+
+      event_types?: Array<string>;
+
+      is_active?: boolean;
+
+      last_delivery_attempt_at?: string | null;
+
+      last_successful_delivery_at?: string | null;
+
+      retry_count?: number;
+
+      signing_secret?: string | null;
+
+      timeout_seconds?: number;
+
+      updated_at?: string | null;
+    }
+  }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface WebhookListEventTypesResponse {
+  /**
+   * The webhook event types a customer can subscribe to.
+   */
+  data?: WebhookListEventTypesResponse.Data | null;
+
+  /**
+   * Error information
+   */
+  error?: WebhookListEventTypesResponse.Error | null;
+
+  /**
+   * Request and response metadata
+   */
+  meta?: WebhookListEventTypesResponse.Meta;
+
+  /**
+   * Indicates whether the request was successful
+   */
+  success?: boolean;
+}
+
+export namespace WebhookListEventTypesResponse {
+  /**
+   * The webhook event types a customer can subscribe to.
+   */
+  export interface Data {
+    /**
+     * The event_types on this page.
+     */
+    event_types?: Array<Data.EventType>;
+
+    /**
+     * Pagination metadata for list responses
+     */
+    pagination?: Data.Pagination;
+  }
+
+  export namespace Data {
+    export interface EventType {
+      description?: string | null;
+
+      display_name?: string;
+
+      event_type?: string | null;
+
+      is_active?: boolean;
+
+      name?: string;
+
+      sub_types?: Array<unknown> | null;
+    }
+
+    /**
+     * Pagination metadata for list responses
+     */
+    export interface Pagination {
+      /**
+       * @deprecated Cursor-based pagination. Never populated — see Cursors.
+       */
+      cursors?: Pagination.Cursors | null;
+
+      /**
+       * Whether there are more pages after this one
+       */
+      has_more?: boolean;
+
+      /**
+       * Current page number (1-indexed)
+       */
+      page?: number;
+
+      /**
+       * Number of items per page
+       */
+      page_size?: number;
+
+      /**
+       * Total number of items across all pages
+       */
+      total_count?: number;
+
+      /**
+       * Total number of pages
+       */
+      total_pages?: number;
+    }
+
+    export namespace Pagination {
+      /**
+       * @deprecated Cursor-based pagination. Never populated — see Cursors.
+       */
+      export interface Cursors {
+        /**
+         * Cursor to fetch the next page.
+         */
+        after?: string | null;
+
+        /**
+         * Cursor to fetch the previous page.
+         */
+        before?: string | null;
+      }
+    }
+  }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface WebhookListEventsResponse {
+  /**
+   * A paginated list of webhook delivery records.
+   */
+  data?: WebhookListEventsResponse.Data | null;
+
+  /**
+   * Error information
+   */
+  error?: WebhookListEventsResponse.Error | null;
+
+  /**
+   * Request and response metadata
+   */
+  meta?: WebhookListEventsResponse.Meta;
+
+  /**
+   * Indicates whether the request was successful
+   */
+  success?: boolean;
+}
+
+export namespace WebhookListEventsResponse {
+  /**
+   * A paginated list of webhook delivery records.
+   */
+  export interface Data {
+    /**
+     * The events on this page.
+     */
+    events?: Array<Data.Event>;
+
+    /**
+     * Pagination metadata for list responses
+     */
+    pagination?: Data.Pagination;
+  }
+
+  export namespace Data {
+    export interface Event {
+      id?: string;
+
+      created_at?: string;
+
+      delivery_attempts?: number;
+
+      delivery_status?: string;
+
+      error_message?: string | null;
+
+      /**
+       * The exact event body that was delivered, or attempted, for this record. One of
+       * the three webhook envelopes: a message status change, an inbound message, or a
+       * template status change. Read field and event to tell which, the same way your
+       * endpoint does.
+       */
+      event_data?: WebhooksAPI.MessageEvent | WebhooksAPI.InboundMessageEvent | WebhooksAPI.TemplateEvent;
+
+      event_type?: string;
+
+      http_status_code?: number | null;
+
+      processing_completed_at?: string | null;
+
+      processing_started_at?: string | null;
+
+      response_body?: string | null;
+    }
+
+    /**
+     * Pagination metadata for list responses
+     */
+    export interface Pagination {
+      /**
+       * @deprecated Cursor-based pagination. Never populated — see Cursors.
+       */
+      cursors?: Pagination.Cursors | null;
+
+      /**
+       * Whether there are more pages after this one
+       */
+      has_more?: boolean;
+
+      /**
+       * Current page number (1-indexed)
+       */
+      page?: number;
+
+      /**
+       * Number of items per page
+       */
+      page_size?: number;
+
+      /**
+       * Total number of items across all pages
+       */
+      total_count?: number;
+
+      /**
+       * Total number of pages
+       */
+      total_pages?: number;
+    }
+
+    export namespace Pagination {
+      /**
+       * @deprecated Cursor-based pagination. Never populated — see Cursors.
+       */
+      export interface Cursors {
+        /**
+         * Cursor to fetch the next page.
+         */
+        after?: string | null;
+
+        /**
+         * Cursor to fetch the previous page.
+         */
+        before?: string | null;
+      }
+    }
+  }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface WebhookRotateSecretResponse {
+  /**
+   * The response data (null if error)
+   */
+  data?: WebhookRotateSecretResponse.Data | null;
+
+  /**
+   * Error information
+   */
+  error?: WebhookRotateSecretResponse.Error | null;
+
+  /**
+   * Request and response metadata
+   */
+  meta?: WebhookRotateSecretResponse.Meta;
+
+  /**
+   * Indicates whether the request was successful
+   */
+  success?: boolean;
+}
+
+export namespace WebhookRotateSecretResponse {
+  /**
+   * The response data (null if error)
+   */
+  export interface Data {
+    signing_secret?: string;
+  }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface WebhookTestResponse {
+  /**
+   * The response data (null if error)
+   */
+  data?: WebhookTestResponse.Data | null;
+
+  /**
+   * Error information
+   */
+  error?: WebhookTestResponse.Error | null;
+
+  /**
+   * Request and response metadata
+   */
+  meta?: WebhookTestResponse.Meta;
+
+  /**
+   * Indicates whether the request was successful
+   */
+  success?: boolean;
+}
+
+export namespace WebhookTestResponse {
+  /**
+   * The response data (null if error)
+   */
+  export interface Data {
+    message?: string;
+
     success?: boolean;
   }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
+  }
+}
+
+/**
+ * Standard API response envelope for all v3 endpoints
+ */
+export interface WebhookToggleStatusResponse {
+  /**
+   * The response data (null if error)
+   */
+  data?: WebhookToggleStatusResponse.Data | null;
+
+  /**
+   * Error information
+   */
+  error?: WebhookToggleStatusResponse.Error | null;
+
+  /**
+   * Request and response metadata
+   */
+  meta?: WebhookToggleStatusResponse.Meta;
+
+  /**
+   * Indicates whether the request was successful
+   */
+  success?: boolean;
+}
+
+export namespace WebhookToggleStatusResponse {
+  /**
+   * The response data (null if error)
+   */
+  export interface Data {
+    id?: string;
+
+    consecutive_failures?: number;
+
+    created_at?: string;
+
+    /**
+     * Which customer owns this — the key's own, or the profile named in x-profile-id.
+     * Says whose resource this is, which the resource's own id does not.
+     */
+    customer_id?: string;
+
+    display_name?: string;
+
+    endpoint_url?: string;
+
+    event_filters?: { [key: string]: Array<string> } | null;
+
+    event_types?: Array<string>;
+
+    is_active?: boolean;
+
+    last_delivery_attempt_at?: string | null;
+
+    last_successful_delivery_at?: string | null;
+
+    retry_count?: number;
+
+    signing_secret?: string | null;
+
+    timeout_seconds?: number;
+
+    updated_at?: string | null;
+  }
+
+  /**
+   * Error information
+   */
+  export interface Error {
+    /**
+     * Machine-readable error code (e.g., "RESOURCE_001")
+     */
+    code?: string;
+
+    /**
+     * Additional validation error details (field-level errors)
+     */
+    details?: { [key: string]: Array<string> } | null;
+
+    /**
+     * URL to documentation about this error
+     */
+    doc_url?: string | null;
+
+    /**
+     * Human-readable error message
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and response metadata
+   */
+  export interface Meta {
+    /**
+     * Unique identifier for this request (for tracing and support)
+     */
+    request_id?: string;
+
+    /**
+     * Server timestamp when the response was generated
+     */
+    timestamp?: string;
+
+    /**
+     * API version used for this request
+     */
+    version?: string;
+  }
 }
 
 export interface WebhookCreateParams {
@@ -908,18 +1896,21 @@ export interface WebhookToggleStatusParams {
 
 export declare namespace Webhooks {
   export {
-    type APIMeta as APIMeta,
-    type APIResponseWebhook as APIResponseWebhook,
-    type ErrorDetail as ErrorDetail,
-    type MutationRequest as MutationRequest,
-    type PaginationMeta as PaginationMeta,
-    type WebhookEventType as WebhookEventType,
-    type WebhookResponse as WebhookResponse,
+    type InboundMessageEvent as InboundMessageEvent,
+    type InboundMessageEventPayload as InboundMessageEventPayload,
+    type MessageEvent as MessageEvent,
+    type MessageEventPayload as MessageEventPayload,
+    type TemplateEvent as TemplateEvent,
+    type TemplateEventPayload as TemplateEventPayload,
+    type WebhookCreateResponse as WebhookCreateResponse,
+    type WebhookRetrieveResponse as WebhookRetrieveResponse,
+    type WebhookUpdateResponse as WebhookUpdateResponse,
     type WebhookListResponse as WebhookListResponse,
     type WebhookListEventTypesResponse as WebhookListEventTypesResponse,
     type WebhookListEventsResponse as WebhookListEventsResponse,
     type WebhookRotateSecretResponse as WebhookRotateSecretResponse,
     type WebhookTestResponse as WebhookTestResponse,
+    type WebhookToggleStatusResponse as WebhookToggleStatusResponse,
     type WebhookCreateParams as WebhookCreateParams,
     type WebhookRetrieveParams as WebhookRetrieveParams,
     type WebhookUpdateParams as WebhookUpdateParams,