注册 Webhook

用于创建、查询和删除通知 Webhook 的接口。

---

创建 Webhook

POST /api/external/webhooks

请求头

请求头	类型	是否必填	说明
Authorization	String	是	ApiKey {client_id}:{client_secret}
Content-Type	String	是	application/json
hmac	String	是	请求体的 HMAC-SHA512 签名（了解更多）

请求体

字段	类型	是否必填	默认值	说明
url	String	是	--	接收通知的 URL（默认要求 HTTPS）
events	Array	否	全部	要订阅的事件列表。如省略，则订阅所有事件。
allow_insecure	boolean	否	false	允许 HTTP（非 HTTPS）URL。数据安全由客户全权负责。

可用事件：pix.charge.created、pix.charge.paid、pix.charge.expired、pix.payout.created、pix.payout.confirmed、pix.payout.failed、pix.payout.returned、pix.refund.requested、pix.refund.completed、pix.return.received、webhook.test

示例

BODY='{"url":"https://yourdomain.com/webhook","events":["pix.charge.paid","pix.payout.confirmed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

成功响应 (201)

{
  "worked": true,
  "webhook": {
    "id": "wh_a1b2c3d4e5f6",
    "url": "https://yourdomain.com/webhook",
    "events": ["pix.charge.paid", "pix.payout.confirmed"],
    "status": "active",
    "created_at": "2026-03-07T15:30:00Z"
  }
}

错误响应 (422)

{
  "worked": false,
  "detail": "URL 必须使用 HTTPS"
}

默认仅支持 HTTPS

Webhook URL 必须使用 HTTPS。HTTP URL 将被拒绝，除非在创建 Webhook 时传入 allow_insecure: true。

HTTP URLs

默认情况下，Webhook 要求使用 HTTPS 以确保数据传输安全。如需使用 HTTP，请在创建 Webhook 时设置 allow_insecure: true。

注意

HTTP URL 以明文方式传输数据。传输信息的安全性和保密性完全由客户负责。Owem Pay 将正常投递 Webhook，但对未加密连接上的数据拦截或泄露不承担任何责任。

---

查询 Webhook 列表

GET /api/external/webhooks

请求头

请求头	类型	是否必填	说明
Authorization	String	是	ApiKey {client_id}:{client_secret}

示例

curl -X GET https://api.owem.com.br/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

成功响应 (200)

{
  "worked": true,
  "webhooks": [
    {
      "id": "wh_a1b2c3d4e5f6",
      "url": "https://yourdomain.com/webhook",
      "events": ["pix.charge.paid", "pix.payout.confirmed"],
      "status": "active",
      "created_at": "2026-03-07T15:30:00Z"
    }
  ]
}

---

删除 Webhook

DELETE /api/external/webhooks/:id

请求头

请求头	类型	是否必填	说明
Authorization	String	是	ApiKey {client_id}:{client_secret}

路径参数

参数	类型	是否必填	说明
id	String	是	Webhook ID

示例

curl -X DELETE https://api.owem.com.br/api/external/webhooks/wh_a1b2c3d4e5f6 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

成功响应 (200)

{
  "worked": true
}

错误响应 (404)

{
  "worked": false,
  "detail": "Webhook 不存在"
}