通过 API 配置 Webhooks

概述

Webhook 配置 API 允许您以编程方式定义应用程序将在何处接收 PIX 事件通知。无需联系技术支持即可配置 webhooks。

Webhook 配置的更改会立即生效。后续交易将使用新配置的 URL。

端点

POST /api/webhooks

认证

需要在 Authorization 请求头中提供账户 Bearer token。

Authorization: Bearer {account_token}

令牌必须通过认证端点使用您的客户端证书获取。

参数

stringobrigatorio

您的 webhook 端点的 HTTPS URL。

要求：

必须使用 HTTPS 协议（不接受 HTTP）
必须是有效且可访问的 URL

示例： https://api.example.com/webhooks/pix

stringobrigatorio

要接收通知的事件类型。

可选值：

cash_in - PIX 收款
cash_out - PIX 付款
refund_in - 收到的付款退款（退款请求）
refund_out - 收到退款

array

用于端点认证的自定义请求头（最多 5 个）。

每个项目必须包含：

key：请求头名称
value：请求头值

被阻止的请求头（不允许）：

host
content-length
connection
transfer-encoding
content-type
user-agent

请求示例

curl -X POST https://api.safirapay.com/api/webhooks \
  -H "Authorization: Bearer {account_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/pix",
    "eventType": "cash_in",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer my-secret-token"
      },
      {
        "key": "X-Webhook-Secret",
        "value": "abc123"
      }
    ]
  }'

const response = await fetch('https://api.safirapay.com/api/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accountToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://api.example.com/webhooks/pix',
    eventType: 'cash_in',
    headers: [
      { key: 'Authorization', value: 'Bearer my-secret-token' },
      { key: 'X-Webhook-Secret', value: 'abc123' },
    ],
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api.safirapay.com/api/webhooks',
    headers={
        'Authorization': f'Bearer {account_token}',
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://api.example.com/webhooks/pix',
        'eventType': 'cash_in',
        'headers': [
            {'key': 'Authorization', 'value': 'Bearer my-secret-token'},
            {'key': 'X-Webhook-Secret', 'value': 'abc123'},
        ],
    },
)

print(response.json())

响应示例

{
  "success": true,
  "message": "Webhook configured successfully"
}

Upsert 行为

如果已为相同的 eventType 配置了 webhook，它将使用新的 URL 和请求头更新。不会创建重复的 webhook。

更新现有 webhook 时，之前的请求头将被新的替换。如果不发送请求头，之前的请求头将被移除。

错误码

状态码	描述
400	URL 无效（非 HTTPS）、事件类型无效或请求头超过 5 个
401	未提供令牌或令牌无效
404	账户未找到
500	配置 webhook 时的内部错误

配置多个事件

要接收多种事件类型的通知，请为每种类型进行一次调用：

const eventTypes = ['cash_in', 'cash_out', 'refund_in', 'refund_out'];

for (const eventType of eventTypes) {
  await fetch('https://api.safirapay.com/api/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accountToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://api.example.com/webhooks/pix',
      eventType,
      headers: [
        { key: 'X-Webhook-Secret', value: 'abc123' },
      ],
    }),
  });
}

您可以对所有事件类型使用相同的 URL，并通过 webhook 负载中的 type 字段进行区分。

后续步骤

负载结构

了解收到的 webhooks 结构

实现

处理 webhooks 的代码示例

重发 Webhook

重发丢失的 webhooks 或用于测试

Cash-In Webhook

PIX 收款 webhook 详情

通过 API 配置 Webhooks

负载结构

实现

重发 Webhook

Cash-In Webhook

本页目录