> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook 생성
> 실시간 이벤트 알림을 수신하기 위한 새 Webhook 엔드포인트를 등록합니다.
HTTP POST를 통해 실시간 이벤트 알림을 수신하기 위한 새 Webhook 엔드포인트를 등록합니다.
### 요청 본문
Webhook 이벤트를 수신할 HTTPS URL.
구독할 이벤트 유형 목록. 사용 가능한 이벤트 유형은 [Webhooks](/ko/features/webhooks)를 참조하십시오.
Webhook 페이로드를 검증하기 위한 서명 시크릿. `whsec_`로 시작해야 합니다.
### 예시
```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/webhooks \
-H "X-API-Key: awx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/agentwallex",
"events": ["payment.completed", "payment.failed", "policy.violated"],
"secret": "whsec_your_signing_secret"
}'
```
```json Response theme={null}
{
"id": "whk_abc123",
"url": "https://your-app.com/webhooks/agentwallex",
"events": ["payment.completed", "payment.failed", "policy.violated"],
"status": "active",
"created_at": "2025-06-01T10:00:00Z"
}
```
## OpenAPI
````yaml POST /api/v1/webhooks
openapi: 3.1.0
info:
title: AgentWallex API
description: >-
REST API for managing AI agent wallets, on-chain transactions, spending
policies, webhooks, and x402 micropayments.
version: 1.0.0
contact:
name: AgentWallex Support
url: https://agentwallex.com
servers:
- url: https://api.agentwallex.com
description: Production
- url: https://api-sandbox.agentwallex.com
description: Sandbox
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Agents
description: Create and manage AI agent wallets.
- name: Transactions
description: Send payments and query transaction history.
- name: Policies
description: Configure spending limits and access controls.
- name: Webhooks
description: Register and manage webhook endpoints.
- name: x402
description: x402 micropayment negotiation and session management.
paths:
/api/v1/webhooks:
post:
tags:
- Webhooks
summary: Create Webhook
description: >-
Register a new webhook endpoint to receive real-time event notifications
via HTTP POST.
operationId: createWebhook
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
- events
- secret
properties:
url:
type: string
format: uri
description: The HTTPS URL that will receive webhook events.
events:
type: array
items:
type: string
description: >-
List of event types to subscribe to (e.g.,
`payment.completed`, `payment.failed`, `policy.violated`).
secret:
type: string
description: >-
Signing secret used to verify webhook payloads. Must start
with `whsec_`.
example:
url: https://your-app.com/webhooks/agentwallex
events:
- payment.completed
- payment.failed
- policy.violated
secret: whsec_your_signing_secret
responses:
'200':
description: Webhook created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
example:
id: whk_abc123
url: https://your-app.com/webhooks/agentwallex
events:
- payment.completed
- payment.failed
- policy.violated
status: active
created_at: '2025-06-01T10:00:00Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
Webhook:
type: object
description: >-
A registered webhook endpoint for receiving real-time event
notifications.
properties:
id:
type: string
description: Unique webhook identifier (e.g., `whk_abc123`).
url:
type: string
format: uri
description: HTTPS URL that receives webhook events.
events:
type: array
items:
type: string
description: List of subscribed event types.
status:
type: string
enum:
- active
- inactive
description: Webhook status.
created_at:
type: string
format: date-time
description: ISO 8601 creation timestamp.
ErrorResponse:
type: object
description: Standard error response.
required:
- code
- type
- message
properties:
code:
type: string
description: Machine-readable error code.
type:
type: string
enum:
- invalid_request_error
- authentication_error
- authorization_error
- not_found_error
- rate_limit_error
- internal_error
description: Error type category.
message:
type: string
description: Human-readable error description.
responses:
BadRequest:
description: Invalid request body or parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: invalid_request
type: invalid_request_error
message: The request body is missing required fields.
Unauthorized:
description: Missing or invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: authentication_failed
type: authentication_error
message: The provided API key is invalid or expired.
Forbidden:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: insufficient_permissions
type: authorization_error
message: You do not have permission to perform this action.
RateLimited:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: rate_limit_exceeded
type: rate_limit_error
message: Too many requests. Please retry after a short delay.
InternalError:
description: Server-side error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: server_error
type: internal_error
message: An unexpected error occurred. Please try again later.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key authentication. Keys are prefixed with `awx_`.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT bearer token authentication.
````