Configurar webhooks de la cuenta

POST /api/webhooks

POST https://api-pay.brasilbitco.in/api/webhooks

Requiere un Bearer token en el header Authorization. Vea Generar Token para obtener uno.

Agrega una URL de webhook para un tipo de evento específico (hasta 3 URLs activas por evento). Si la misma URL ya está registrada para ese tipo de evento, se actualiza (headers y version) — las demás URLs registradas no se ven afectadas. Al disparar el evento, la notificación se envía en fan-out a todas las URLs activas de ese evento.

Autenticación

Requiere un Bearer token en el header Authorization.

Eventos disponibles

Evento	Descripción
`cash_in`	PIX recibido
`cash_out`	PIX enviado
`refund_in`	Reembolso de pago recibido (reembolso solicitado)
`refund_out`	Reembolso recibido
`med_created`	MED (Mecanismo Especial de Devolución) abierto contra una transacción
`med_accepted`	Solicitud de devolución MED aprobada
`med_rejected`	Solicitud de devolución MED rechazada

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`url`	string	Sí	URL HTTPS del endpoint que recibirá los webhooks
`eventType`	string	Sí	Tipo de evento: `cash_in`, `cash_out`, `refund_in`, `refund_out`, `med_created`, `med_accepted`, `med_rejected`
`headers`	array	No	Headers personalizados para autenticación (máximo 5). Headers bloqueados: `host`, `content-length`, `connection`, `transfer-encoding`, `content-type`, `user-agent`
`headers[].key`	string	Sí	Nombre del header
`headers[].value`	string	Sí	Valor del header

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

Ejemplos de Código

cURL

curl -X POST "https://api-pay.brasilbitco.in/api/webhooks" \
  -H "Authorization: Bearer $BRBTC_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-pay.brasilbitco.in/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.BRBTC_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api-pay.brasilbitco.in/api/webhooks',
    headers={
        'Authorization': f'Bearer {os.environ["BRBTC_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-pay.brasilbitco.in/api/webhooks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BRBTC_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-pay.brasilbitco.in/api/webhooks"))
    .header("Authorization", "Bearer " + System.getenv("BRBTC_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());

Respuesta (200)

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación fue exitosa
`message`	string	Mensaje descriptivo del resultado

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

Errores

Estado	Descripción
400	Datos inválidos (la URL no es HTTPS, tipo de evento inválido, más de 5 headers o más de 3 URLs activas por evento)
401	Token faltante o inválido
404	Cuenta no encontrada
500	Error interno al configurar el webhook