配置账户 webhook

POST /api/webhooks

POST https://api.avista.global/api/webhooks

需要在 Authorization 头中提供 Bearer token。请参阅生成令牌获取。

为特定事件类型配置或更新 webhook URL。如果同一事件类型已存在 webhook，将进行更新（upsert 行为）。

认证

需要在 Authorization 头中提供 Bearer 令牌。

可用事件

事件	描述
`cash_in`	收到 PIX 付款
`cash_out`	发送 PIX 付款
`refund_in`	已收付款的退款（发起退款请求）
`refund_out`	收到退款
`med_created`	针对交易开启 MED（特殊退款机制）
`med_accepted`	MED 退款请求已批准
`med_rejected`	MED 退款请求已拒绝

请求体

字段	类型	必填	描述
`url`	string	是	接收 webhooks 的端点 HTTPS URL
`eventType`	string	是	事件类型：`cash_in`、`cash_out`、`refund_in`、`refund_out`、`med_created`、`med_accepted`、`med_rejected`
`headers`	array	否	用于身份验证的自定义请求头（最多 5 个）。禁用的请求头：`host`、`content-length`、`connection`、`transfer-encoding`、`content-type`、`user-agent`
`headers[].key`	string	是	请求头名称
`headers[].value`	string	是	请求头值

{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}

代码示例

cURL

curl -X POST "https://api.avista.global/api/webhooks" \
  -H "Authorization: Bearer $AVISTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}'

const axios = require('axios');

const response = await axios.post('https://api.avista.global/api/webhooks',
  {
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.AVISTA_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.avista.global/api/webhooks',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/webhooks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "url": "https://api.example.com/webhooks/pix",
      "eventType": "cash_in",
      "headers": [
        { "key": "Authorization", "value": "Bearer token123" },
        { "key": "X-Webhook-Secret", "value": "abc123" }
      ]
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/webhooks"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

响应 (200)

字段	类型	描述
`success`	boolean	表示操作是否成功
`message`	string	结果描述信息

{
  "success": true,
  "message": "Webhook configurado com sucesso"
}

错误

状态码	描述
400	数据无效（URL 非 HTTPS、事件类型无效等）
401	令牌缺失或无效
404	账户未找到
500	配置 webhook 时内部错误

配置账户 webhook

POST /api/webhooks

认证

可用事件

请求体

代码示例

响应 (200)

错误

本页目录