> ## 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.
# Tạo Webhook
> Đăng ký endpoint Webhook mới để nhận thông báo sự kiện theo thời gian thực.
Đăng ký endpoint Webhook mới để nhận thông báo sự kiện theo thời gian thực qua HTTP POST.
### Nội dung yêu cầu
URL HTTPS sẽ nhận các sự kiện Webhook.
Danh sách loại sự kiện cần đăng ký. Xem [Webhooks](/vi/features/webhooks) để biết các loại sự kiện có sẵn.
Khóa ký để xác minh payload Webhook. Phải bắt đầu bằng `whsec_`.
### Ví dụ
```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.
````