> ## Documentation Index > Fetch the complete documentation index at: https://docs.natural.com/llms.txt > Use this file to discover all available pages before exploring further. # List webhooks > List webhook endpoints for the authenticated party. ## OpenAPI ````yaml /api-reference/openapi.json get /webhooks openapi: 3.1.1 info: title: Natural API version: 0.2.0 description: >- Natural's payments API for autonomous agents. **Base URL:** `https://api.natural.co` Agents and coding assistants should prefer the hosted MCP server at `https://mcp.natural.co` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required. For support: support@natural.co servers: - url: https://api.natural.co description: Production security: [] tags: - name: Agents description: Agent management - name: Customers description: Customer management - name: Counterparties description: Counterparty management - name: Payments description: Payment operations - name: Transactions description: Transaction activity and history operations - name: Transfers description: Deposit and withdrawal operations - name: PaymentRequests description: Payment-request management - name: Approvals description: Approval review operations - name: Invitations description: Party invitation management - name: Identity description: Caller identity introspection - name: Parties description: Party and organization management - name: Wallets description: Wallet balance, deposits, withdrawals, and external accounts - name: External Accounts description: Linked external bank accounts - name: API Keys description: API key management - name: Agent Keys description: Agent key management - name: Webhooks description: Webhook endpoint management - name: Events description: Webhook event log access paths: /webhooks: get: tags: - Webhooks summary: List webhooks description: List webhook endpoints for the authenticated party. operationId: webhooks.list parameters: - name: status in: query schema: enum: - ENABLED - DISABLED type: string description: Filter by status allowEmptyValue: true allowReserved: true - name: cursor in: query schema: type: string description: Cursor for keyset pagination allowEmptyValue: true allowReserved: true - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Max items per page (1-100) allowEmptyValue: true allowReserved: true - name: X-Agent-ID in: header required: false schema: anyOf: - type: string - type: 'null' description: Agent ID (agt_xxx) identifying which agent is making the request. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: >- Required when X-Agent-ID is present. Session or conversation ID for agent observability. responses: '200': description: Successful Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: type: description: Resource type type: string enum: - webhook id: type: string description: Resource ID (whk_xxx) attributes: type: object properties: url: type: string format: uri description: Webhook endpoint URL description: type: string description: Human-readable description status: enum: - ENABLED - DISABLED type: string description: Webhook status enabledEvents: type: array items: enum: - '*' - party.updated - compliance_case.updated - wallet.created - external_account.connected - agent_delegation_invitation.created - agent_delegation_invitation.accepted - agent_delegation_invitation.declined - agent_delegation_invitation.canceled - agent_delegation.revoked - delegation.activated - delegation.revoked - deposit.created - deposit.completed - deposit.failed - deposit.returned - deposit.canceled - deposit.approval_denied - withdrawal.created - withdrawal.completed - withdrawal.failed - withdrawal.returned - withdrawal.canceled - withdrawal.approval_denied - payment.created - payment.completed - payment.failed - payment.returned - payment.canceled - payment.approval_denied - approval.required - approval.approved - approval.denied - approval.canceled - payment_request.created - payment_request.completed - payment_request.canceled - payment_request.declined - payment_request.incoming type: string description: Event types this webhook listens to tags: type: object propertyNames: type: string additionalProperties: type: string description: >- Custom metadata tags. Visible to any party authorized to read the resource. createdAt: type: string format: date-time description: Creation timestamp (ISO 8601) updatedAt: type: string format: date-time description: Last update timestamp (ISO 8601) required: - url - description - status - enabledEvents - tags - createdAt - updatedAt additionalProperties: false title: WebhookAttributes description: Resource attributes relationships: type: object properties: party: type: object properties: data: type: object properties: type: description: Resource type type: string enum: - party id: type: string required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier required: - data additionalProperties: false title: ToOneRelationship description: Party that owns the webhook required: - party additionalProperties: false title: WebhookRelationships description: Resource relationships required: - type - id - attributes - relationships additionalProperties: false title: WebhookResource meta: type: object properties: pagination: type: object properties: hasMore: type: boolean nextCursor: anyOf: - type: string - type: 'null' required: - hasMore - nextCursor additionalProperties: false title: PaginationMeta required: - pagination additionalProperties: false required: - data - meta additionalProperties: false title: WebhookListResponse examples: default: summary: Default value: data: - type: webhook id: whk_0192abc1def2789034567890abcdef12 attributes: url: https://example.com/webhooks/natural description: Production webhook for wallet and party events status: ENABLED enabledEvents: - wallet.created - party.updated - delegation.activated tags: env: prod team: payments createdAt: '2026-03-16T12:00:00Z' updatedAt: '2026-03-16T12:00:00Z' relationships: party: data: type: party id: pty_7c9e6679e29b41d4a716446655440001 - type: webhook id: whk_0192def4abc1789034567890abcdef34 attributes: url: https://example.com/webhooks/funding description: External account notifications status: DISABLED enabledEvents: - external_account.connected tags: env: prod createdAt: '2026-03-10T09:00:00Z' updatedAt: '2026-03-14T18:30:00Z' relationships: party: data: type: party id: pty_7c9e6679e29b41d4a716446655440001 meta: pagination: hasMore: false nextCursor: null headers: X-RateLimit-Limit: description: Maximum requests allowed per window schema: type: integer X-RateLimit-Remaining: description: Requests remaining in current window schema: type: integer X-RateLimit-Reset: description: Unix timestamp when rate limit resets schema: type: integer '400': description: Validation Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: invalid_value detail: A request value is invalid. status: '400' meta: supportId: req_a1b2c3d4e5f6 '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: unauthenticated detail: Authentication is required. status: '401' meta: supportId: req_a1b2c3d4e5f6 '403': description: Forbidden content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: >- Not Found — returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': description: Validation Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: invalid_value detail: 'email: Invalid email address' status: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying schema: type: integer X-RateLimit-Limit: description: Maximum requests allowed per window schema: type: integer X-RateLimit-Remaining: description: Requests remaining in current window schema: type: integer X-RateLimit-Reset: description: Unix timestamp when rate limit resets schema: type: integer '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: bad_gateway detail: >- We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] components: securitySchemes: HTTPBearer: type: http scheme: bearer ````