> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Webhook

> 注册回调 URL，以接收订单、资金活动、全球支付、稳定币支付或加密货币提现的实时事件通知。

使用此端点注册一个 Webhook URL，当特定事件类型发生时，VelaFi 将调用该 URL。每次注册仅对应一种事件类型，因此请为每个需要接收的事件分别创建 Webhook。如果该事件类型已存在一个活跃的 Webhook，请求将被拒绝。Webhook 归属于您的账户，因此一个 Webhook 会接收账户下所有商户的对应事件。响应中包含一个您必须保存的 `publicKey`——它用于验证此端点后续所有 Webhook 推送上的 RSA-SHA256 签名。

> [!NOTE]
>
> 所有请求都必须包含 `X-BH-TOKEN` 请求头和 `Content-Type: application/json`。请安全保存响应中的 `publicKey`。它也会由[列出 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/get-webhook-endpoints.md) 返回。

## 端点

`POST https://api.velafi.com/v2/webhook`

## 请求参数

**eventType** `string` *required*

此 Webhook 应接收的事件类型。可接受的值：

* `ORDER_WEBHOOK` — 法币/加密货币订单状态变更
* `GLOBAL_PAYMENT_WEBHOOK` — 法币/法币全球支付状态变更
* `FUNDING_WEBHOOK` — 待处理资金（Pending Fund）账户活动
* `ON_RAMP_WITHDRAW_WEBHOOK` — 已完成的 API 入金订单向目标钱包的加密货币提现成功
* `STABLE_COIN_PAYMENT_WEBHOOK` — 稳定币支付订单已确认
* `CRYPTO_WITHDRAW_WEBHOOK` — 商户钱包的加密货币提现成功、失败或被取消

**url** `string` *required*

VelaFi 将向其 POST 事件通知的可公开访问的 URL。必须以 `http` 开头。请使用 `https://` URL。

## 响应字段

**code** `number`

HTTP 风格的响应码。`200` 表示成功。

**msg** `string`

人类可读的状态消息，例如 `SUCCESS`。

**data** `object`

**data 字段**

**webhookId** `string`

此 Webhook 注册的唯一标识符。

**eventType** `string`

此 Webhook 所注册的事件类型。

**url** `string`

已注册的回调 URL。

**status** `number`

Webhook 状态：`10` = 活跃，`20` = 已禁用，`30` = 已删除。

**publicKey** `string`

Base64 编码的 RSA 公钥，用于验证传入 Webhook 请求上的 `signature` 请求头。它也会由[列出 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/get-webhook-endpoints.md) 返回。

## 示例

```bash cURL theme={null}
curl -X POST https://api.velafi.com/v2/webhook \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "ORDER_WEBHOOK",
    "url": "https://your-app.com/webhooks/velafi"
  }'
```

```json Response theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
    "eventType": "ORDER_WEBHOOK",
    "url": "https://your-app.com/webhooks/velafi",
    "status": 10,
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGz..."
  }
}
```

> [!WARNING]
>
> 如果您丢失了 `publicKey`，可以通过[列出 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/get-webhook-endpoints.md) 重新获取。有关如何使用公钥验证传入请求，请参阅 [Webhook 设置](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md)。


## Related topics

- [Webhook 设置](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md)
- [加密货币提现事件](https://docs.velafi.com/cn/api-reference/webhooks/crypto-withdraw-message-push.md)
- [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.md)
- [删除 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/delete-a-webhook.md)
- [更新 Webhook](https://docs.velafi.com/cn/api-reference/webhooks/update-a-webhook.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.