OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys Webhooks API
version: 0.2.0
description: 'Natural''s payments API for autonomous agents.
**Base URL:** `https://api.natural.com`
AI agents, including coding agents, should prefer the hosted MCP server at `https://mcp.natural.com` 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.com'
servers:
- url: https://api.natural.com
description: Production
tags:
- name: Webhooks
description: Webhook endpoint management
paths:
/webhooks:
post:
operationId: webhooks.create
summary: Create webhook
description: Create a webhook endpoint. The signing secret is returned only once.
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
url:
type: string
maxLength: 2048
format: uri
description: Webhook endpoint URL.
description:
type: string
maxLength: 100
description: Webhook description.
enabledEvents:
type: array
minItems: 1
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 to subscribe to; use "*" to subscribe to all event types.
tags:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_]+$
additionalProperties:
type: string
minLength: 1
maxLength: 256
description: Tags applied to this webhook.
required:
- url
- enabledEvents
additionalProperties: false
title: WebhookCreateAttributes
required:
- attributes
additionalProperties: false
title: WebhookCreateData
required:
- data
additionalProperties: false
title: CreateWebhookInput
examples:
default:
summary: Default
value:
data:
attributes:
url: https://example.com/webhooks/natural
description: Production webhook for wallet and party events
enabledEvents:
- wallet.created
- party.updated
- delegation.activated
tags:
env: prod
team: payments
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- webhook
id:
type: string
description: Webhook ID (whk_*).
attributes:
type: object
properties:
url:
type: string
format: uri
description: Webhook endpoint URL.
description:
type: string
description: Webhook 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: Metadata visible to anyone who can read the resource.
createdAt:
type: string
format: date-time
description: When this webhook was created.
updatedAt:
type: string
format: date-time
description: When this webhook was last updated.
signingSecret:
type: string
description: Webhook signing secret. Returned only once.
required:
- url
- description
- status
- enabledEvents
- tags
- createdAt
- updatedAt
- signingSecret
additionalProperties: false
title: WebhookCreateResultAttributes
relationships:
type: object
properties:
party:
type: object
properties:
data:
type: object
properties:
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
required:
- type
- id
- attributes
- relationships
additionalProperties: false
title: WebhookCreateResource
required:
- data
additionalProperties: false
title: WebhookCreateSingleResponse
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'
signingSecret: whsec_3JZ8aQpL2vR7nXdE5fW1cT0yK6mB4hG9
relationships:
party:
data:
type: party
id: pty_7c9e6679e29b41d4a716446655440001
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
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
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
description: Provider error details, when available.
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: The information you entered isn't valid. Please check it and try again.
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
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
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
description: Provider error details, when available.
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
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
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
description: Provider error details, when available.
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
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
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
description: Provider error details, when available.
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
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
# --- truncated at 32 KB (364 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-webhooks-api-openapi.yml