@naturalpay/sdk 0.2.1 → 0.4.0

package/src/resources/webhooks.ts

@@ -0,0 +1,1232 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Webhook endpoint management
+ */
+export class Webhooks extends APIResource {
+  /**
+   * Create a new webhook endpoint. The signing secret is returned only once.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.create({
+   *   enabledEvents: ['*'],
+   *   url: 'https://example.com',
+   *   'Idempotency-Key': 'Idempotency-Key',
+   * });
+   * ```
+   */
+  create(params: WebhookCreateParams, options?: RequestOptions): APIPromise<WebhookCreateResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.post('/webhooks', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Partially update a webhook endpoint.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.update('webhookId', {
+   *   'Idempotency-Key': 'Idempotency-Key',
+   * });
+   * ```
+   */
+  update(
+    webhookID: string,
+    params: WebhookUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<WebhookUpdateResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.put(path`/webhooks/${webhookID}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * List webhook endpoints for the authenticated party.
+   *
+   * @example
+   * ```ts
+   * const webhooks = await client.webhooks.list();
+   * ```
+   */
+  list(
+    params: WebhookListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WebhookListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/webhooks', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get details of a specific webhook endpoint.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.get('webhookId');
+   * ```
+   */
+  get(
+    webhookID: string,
+    params: WebhookGetParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WebhookGetResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.get(path`/webhooks/${webhookID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Soft-delete a webhook endpoint.
+   *
+   * @example
+   * ```ts
+   * const webhook = await client.webhooks.remove('webhookId', {
+   *   'Idempotency-Key': 'Idempotency-Key',
+   * });
+   * ```
+   */
+  remove(
+    webhookID: string,
+    params: WebhookRemoveParams,
+    options?: RequestOptions,
+  ): APIPromise<WebhookRemoveResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+    } = params;
+    return this._client.delete(path`/webhooks/${webhookID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Generate a new signing secret. The previous secret remains valid for the
+   * specified grace period. Requires Idempotency-Key header.
+   *
+   * @example
+   * ```ts
+   * const response = await client.webhooks.rotateSecret(
+   *   'webhookId',
+   *   {
+   *     expiresInSeconds: 0,
+   *     'Idempotency-Key': 'Idempotency-Key',
+   *   },
+   * );
+   * ```
+   */
+  rotateSecret(
+    webhookID: string,
+    params: WebhookRotateSecretParams,
+    options?: RequestOptions,
+  ): APIPromise<WebhookRotateSecretResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.post(path`/webhooks/${webhookID}/rotate-secret`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface WebhookCreateResponse {
+  data: WebhookCreateResponse.Data;
+}
+
+export namespace WebhookCreateResponse {
+  export interface Data {
+    /**
+     * Resource ID (whk_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Creation timestamp (ISO 8601)
+       */
+      createdAt: string;
+
+      /**
+       * Human-readable description
+       */
+      description: string;
+
+      /**
+       * Event types this webhook listens to
+       */
+      enabledEvents: Array<
+        | '*'
+        | 'party.updated'
+        | 'party.delegation_granted'
+        | 'wallet.created'
+        | 'external_account.connected'
+        | 'agent_delegation_invitation.created'
+        | 'agent_delegation_invitation.accepted'
+        | 'agent_delegation_invitation.declined'
+        | 'agent_delegation_invitation.cancelled'
+        | 'agent_delegation.revoked'
+        | 'delegation.activated'
+        | 'delegation.revoked'
+        | 'deposit.created'
+        | 'deposit.completed'
+        | 'deposit.failed'
+        | 'deposit.returned'
+        | 'withdrawal.created'
+        | 'withdrawal.completed'
+        | 'withdrawal.failed'
+        | 'withdrawal.returned'
+        | 'payment.created'
+        | 'payment.completed'
+        | 'payment.failed'
+        | 'payment_request.created'
+        | 'payment_request.completed'
+        | 'payment_request.failed'
+        | 'payment_request.returned'
+        | 'payment_request.incoming'
+      >;
+
+      /**
+       * Webhook signing secret (shown only once — store securely!)
+       */
+      signingSecret: string;
+
+      /**
+       * Webhook status
+       */
+      status: 'ENABLED' | 'DISABLED';
+
+      /**
+       * Custom metadata tags
+       */
+      tags: { [key: string]: string };
+
+      /**
+       * Last update timestamp (ISO 8601)
+       */
+      updatedAt: string;
+
+      /**
+       * Webhook endpoint URL
+       */
+      url: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface WebhookUpdateResponse {
+  data: WebhookUpdateResponse.Data;
+}
+
+export namespace WebhookUpdateResponse {
+  export interface Data {
+    /**
+     * Resource ID (whk_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Creation timestamp (ISO 8601)
+       */
+      createdAt: string;
+
+      /**
+       * Human-readable description
+       */
+      description: string;
+
+      /**
+       * Event types this webhook listens to
+       */
+      enabledEvents: Array<
+        | '*'
+        | 'party.updated'
+        | 'party.delegation_granted'
+        | 'wallet.created'
+        | 'external_account.connected'
+        | 'agent_delegation_invitation.created'
+        | 'agent_delegation_invitation.accepted'
+        | 'agent_delegation_invitation.declined'
+        | 'agent_delegation_invitation.cancelled'
+        | 'agent_delegation.revoked'
+        | 'delegation.activated'
+        | 'delegation.revoked'
+        | 'deposit.created'
+        | 'deposit.completed'
+        | 'deposit.failed'
+        | 'deposit.returned'
+        | 'withdrawal.created'
+        | 'withdrawal.completed'
+        | 'withdrawal.failed'
+        | 'withdrawal.returned'
+        | 'payment.created'
+        | 'payment.completed'
+        | 'payment.failed'
+        | 'payment_request.created'
+        | 'payment_request.completed'
+        | 'payment_request.failed'
+        | 'payment_request.returned'
+        | 'payment_request.incoming'
+      >;
+
+      /**
+       * Webhook status
+       */
+      status: 'ENABLED' | 'DISABLED';
+
+      /**
+       * Custom metadata tags
+       */
+      tags: { [key: string]: string };
+
+      /**
+       * Last update timestamp (ISO 8601)
+       */
+      updatedAt: string;
+
+      /**
+       * Webhook endpoint URL
+       */
+      url: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface WebhookListResponse {
+  data: Array<WebhookListResponse.Data>;
+
+  meta: WebhookListResponse.Meta;
+}
+
+export namespace WebhookListResponse {
+  export interface Data {
+    /**
+     * Resource ID (whk_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Creation timestamp (ISO 8601)
+       */
+      createdAt: string;
+
+      /**
+       * Human-readable description
+       */
+      description: string;
+
+      /**
+       * Event types this webhook listens to
+       */
+      enabledEvents: Array<
+        | '*'
+        | 'party.updated'
+        | 'party.delegation_granted'
+        | 'wallet.created'
+        | 'external_account.connected'
+        | 'agent_delegation_invitation.created'
+        | 'agent_delegation_invitation.accepted'
+        | 'agent_delegation_invitation.declined'
+        | 'agent_delegation_invitation.cancelled'
+        | 'agent_delegation.revoked'
+        | 'delegation.activated'
+        | 'delegation.revoked'
+        | 'deposit.created'
+        | 'deposit.completed'
+        | 'deposit.failed'
+        | 'deposit.returned'
+        | 'withdrawal.created'
+        | 'withdrawal.completed'
+        | 'withdrawal.failed'
+        | 'withdrawal.returned'
+        | 'payment.created'
+        | 'payment.completed'
+        | 'payment.failed'
+        | 'payment_request.created'
+        | 'payment_request.completed'
+        | 'payment_request.failed'
+        | 'payment_request.returned'
+        | 'payment_request.incoming'
+      >;
+
+      /**
+       * Webhook status
+       */
+      status: 'ENABLED' | 'DISABLED';
+
+      /**
+       * Custom metadata tags
+       */
+      tags: { [key: string]: string };
+
+      /**
+       * Last update timestamp (ISO 8601)
+       */
+      updatedAt: string;
+
+      /**
+       * Webhook endpoint URL
+       */
+      url: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    pagination: Meta.Pagination;
+  }
+
+  export namespace Meta {
+    export interface Pagination {
+      hasMore: boolean;
+
+      nextCursor: string | null;
+    }
+  }
+}
+
+export interface WebhookGetResponse {
+  data: WebhookGetResponse.Data;
+}
+
+export namespace WebhookGetResponse {
+  export interface Data {
+    /**
+     * Resource ID (whk_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Creation timestamp (ISO 8601)
+       */
+      createdAt: string;
+
+      /**
+       * Human-readable description
+       */
+      description: string;
+
+      /**
+       * Event types this webhook listens to
+       */
+      enabledEvents: Array<
+        | '*'
+        | 'party.updated'
+        | 'party.delegation_granted'
+        | 'wallet.created'
+        | 'external_account.connected'
+        | 'agent_delegation_invitation.created'
+        | 'agent_delegation_invitation.accepted'
+        | 'agent_delegation_invitation.declined'
+        | 'agent_delegation_invitation.cancelled'
+        | 'agent_delegation.revoked'
+        | 'delegation.activated'
+        | 'delegation.revoked'
+        | 'deposit.created'
+        | 'deposit.completed'
+        | 'deposit.failed'
+        | 'deposit.returned'
+        | 'withdrawal.created'
+        | 'withdrawal.completed'
+        | 'withdrawal.failed'
+        | 'withdrawal.returned'
+        | 'payment.created'
+        | 'payment.completed'
+        | 'payment.failed'
+        | 'payment_request.created'
+        | 'payment_request.completed'
+        | 'payment_request.failed'
+        | 'payment_request.returned'
+        | 'payment_request.incoming'
+      >;
+
+      /**
+       * Webhook status
+       */
+      status: 'ENABLED' | 'DISABLED';
+
+      /**
+       * Custom metadata tags
+       */
+      tags: { [key: string]: string };
+
+      /**
+       * Last update timestamp (ISO 8601)
+       */
+      updatedAt: string;
+
+      /**
+       * Webhook endpoint URL
+       */
+      url: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface WebhookRemoveResponse {
+  data: WebhookRemoveResponse.Data;
+
+  meta: WebhookRemoveResponse.Meta;
+}
+
+export namespace WebhookRemoveResponse {
+  export interface Data {
+    /**
+     * Resource ID (whk_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Creation timestamp (ISO 8601)
+       */
+      createdAt: string;
+
+      /**
+       * Human-readable description
+       */
+      description: string;
+
+      /**
+       * Event types this webhook listens to
+       */
+      enabledEvents: Array<
+        | '*'
+        | 'party.updated'
+        | 'party.delegation_granted'
+        | 'wallet.created'
+        | 'external_account.connected'
+        | 'agent_delegation_invitation.created'
+        | 'agent_delegation_invitation.accepted'
+        | 'agent_delegation_invitation.declined'
+        | 'agent_delegation_invitation.cancelled'
+        | 'agent_delegation.revoked'
+        | 'delegation.activated'
+        | 'delegation.revoked'
+        | 'deposit.created'
+        | 'deposit.completed'
+        | 'deposit.failed'
+        | 'deposit.returned'
+        | 'withdrawal.created'
+        | 'withdrawal.completed'
+        | 'withdrawal.failed'
+        | 'withdrawal.returned'
+        | 'payment.created'
+        | 'payment.completed'
+        | 'payment.failed'
+        | 'payment_request.created'
+        | 'payment_request.completed'
+        | 'payment_request.failed'
+        | 'payment_request.returned'
+        | 'payment_request.incoming'
+      >;
+
+      /**
+       * Webhook status
+       */
+      status: 'ENABLED' | 'DISABLED';
+
+      /**
+       * Custom metadata tags
+       */
+      tags: { [key: string]: string };
+
+      /**
+       * Last update timestamp (ISO 8601)
+       */
+      updatedAt: string;
+
+      /**
+       * Webhook endpoint URL
+       */
+      url: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    /**
+     * Indicates the resource was deleted
+     */
+    deleted: true;
+  }
+}
+
+export interface WebhookRotateSecretResponse {
+  data: WebhookRotateSecretResponse.Data;
+}
+
+export namespace WebhookRotateSecretResponse {
+  export interface Data {
+    /**
+     * Resource ID (whk_xxx)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * When the previous secret expires (null if immediate cutover)
+       */
+      previousSecretExpiresAt: string | null;
+
+      /**
+       * New webhook signing secret (shown only once — store securely!)
+       */
+      signingSecret: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the webhook
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface WebhookCreateParams {
+  /**
+   * Body param: Event types to subscribe to
+   */
+  enabledEvents: Array<
+    | '*'
+    | 'party.updated'
+    | 'party.delegation_granted'
+    | 'wallet.created'
+    | 'external_account.connected'
+    | 'agent_delegation_invitation.created'
+    | 'agent_delegation_invitation.accepted'
+    | 'agent_delegation_invitation.declined'
+    | 'agent_delegation_invitation.cancelled'
+    | 'agent_delegation.revoked'
+    | 'delegation.activated'
+    | 'delegation.revoked'
+    | 'deposit.created'
+    | 'deposit.completed'
+    | 'deposit.failed'
+    | 'deposit.returned'
+    | 'withdrawal.created'
+    | 'withdrawal.completed'
+    | 'withdrawal.failed'
+    | 'withdrawal.returned'
+    | 'payment.created'
+    | 'payment.completed'
+    | 'payment.failed'
+    | 'payment_request.created'
+    | 'payment_request.completed'
+    | 'payment_request.failed'
+    | 'payment_request.returned'
+    | 'payment_request.incoming'
+  >;
+
+  /**
+   * Body param: Webhook endpoint URL
+   */
+  url: string;
+
+  /**
+   * Header param: Unique key for idempotent request handling. If a request with the
+   * same key was already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
+  /**
+   * Body param: Human-readable description
+   */
+  description?: string;
+
+  /**
+   * Body param: Custom metadata tags
+   */
+  tags?: { [key: string]: string };
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface WebhookUpdateParams {
+  /**
+   * Header param: Unique key for idempotent request handling. If a request with the
+   * same key was already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
+  /**
+   * Body param: New description
+   */
+  description?: string;
+
+  /**
+   * Body param: Event types to subscribe to
+   */
+  enabledEvents?: Array<
+    | '*'
+    | 'party.updated'
+    | 'party.delegation_granted'
+    | 'wallet.created'
+    | 'external_account.connected'
+    | 'agent_delegation_invitation.created'
+    | 'agent_delegation_invitation.accepted'
+    | 'agent_delegation_invitation.declined'
+    | 'agent_delegation_invitation.cancelled'
+    | 'agent_delegation.revoked'
+    | 'delegation.activated'
+    | 'delegation.revoked'
+    | 'deposit.created'
+    | 'deposit.completed'
+    | 'deposit.failed'
+    | 'deposit.returned'
+    | 'withdrawal.created'
+    | 'withdrawal.completed'
+    | 'withdrawal.failed'
+    | 'withdrawal.returned'
+    | 'payment.created'
+    | 'payment.completed'
+    | 'payment.failed'
+    | 'payment_request.created'
+    | 'payment_request.completed'
+    | 'payment_request.failed'
+    | 'payment_request.returned'
+    | 'payment_request.incoming'
+  >;
+
+  /**
+   * Body param: New status
+   */
+  status?: 'ENABLED' | 'DISABLED';
+
+  /**
+   * Body param: Tag updates (set value to empty string to remove key)
+   */
+  tags?: { [key: string]: string };
+
+  /**
+   * Body param: New webhook endpoint URL
+   */
+  url?: string;
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface WebhookListParams {
+  /**
+   * Query param: Cursor for keyset pagination
+   */
+  cursor?: string;
+
+  /**
+   * Query param: Max items per page (1-100)
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter by status
+   */
+  status?: 'ENABLED' | 'DISABLED';
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface WebhookGetParams {
+  /**
+   * Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface WebhookRemoveParams {
+  /**
+   * Unique key for idempotent request handling. If a request with the same key was
+   * already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
+  /**
+   * Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface WebhookRotateSecretParams {
+  /**
+   * Body param: Grace period in seconds for the previous secret (0 = immediate
+   * cutover, max 86400)
+   */
+  expiresInSeconds: number;
+
+  /**
+   * Header param: Unique key for idempotent request handling. If a request with the
+   * same key was already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export declare namespace Webhooks {
+  export {
+    type WebhookCreateResponse as WebhookCreateResponse,
+    type WebhookUpdateResponse as WebhookUpdateResponse,
+    type WebhookListResponse as WebhookListResponse,
+    type WebhookGetResponse as WebhookGetResponse,
+    type WebhookRemoveResponse as WebhookRemoveResponse,
+    type WebhookRotateSecretResponse as WebhookRotateSecretResponse,
+    type WebhookCreateParams as WebhookCreateParams,
+    type WebhookUpdateParams as WebhookUpdateParams,
+    type WebhookListParams as WebhookListParams,
+    type WebhookGetParams as WebhookGetParams,
+    type WebhookRemoveParams as WebhookRemoveParams,
+    type WebhookRotateSecretParams as WebhookRotateSecretParams,
+  };
+}