Configurar Webhooks vía API

Descripción General

La API de configuración de webhooks le permite definir programáticamente dónde su aplicación recibirá notificaciones de eventos PIX. Esto elimina la necesidad de contactar a soporte para configurar webhooks.

Los cambios en la configuración de webhooks se aplican inmediatamente. Las transacciones posteriores usarán las URLs configuradas.

Endpoint

POST /api/webhooks

Autenticación

Requiere un Bearer token de Cuenta en el encabezado Authorization.

Authorization: Bearer {account_token}

El token debe obtenerse a través del endpoint de autenticación usando su certificado de cliente.

Parámetros

stringobrigatorio

URL HTTPS de su endpoint de webhook.

Requisitos:

Debe usar protocolo HTTPS (HTTP no es aceptado)
Debe ser una URL válida y accesible

Ejemplo: https://api.example.com/webhooks/pix

stringobrigatorio

Tipo de evento para el que desea recibir notificaciones.

Valores posibles:

cash_in - PIX recibido
cash_out - PIX enviado
refund_in - Devolución de pago recibido (devolución solicitada)
refund_out - Devolución recibida
med_created - MED (Mecanismo Especial de Devolución) abierto contra una transacción recibida
med_accepted - Solicitud de devolución MED aprobada
med_rejected - Solicitud de devolución MED rechazada

array

Encabezados personalizados para la autenticación de su endpoint (máximo 5).

Cada elemento debe tener:

key: Nombre del encabezado
value: Valor del encabezado

Encabezados bloqueados (no permitidos):

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

Ejemplo de Solicitud

curl -X POST https://api-pay.brasilbitco.in/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-pay.brasilbitco.in/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-pay.brasilbitco.in/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())

Ejemplo de Respuesta

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

Múltiples URLs por Evento

Puede registrar hasta 3 URLs activas para el mismo eventType. Cada llamada a este endpoint agrega una nueva URL al evento — las demás URLs ya registradas permanecen activas y no son reemplazadas.

Si reenvía una URL que ya está registrada para ese eventType, será actualizada (encabezados y version), sin crear un webhook duplicado.

Cuando ocurre el evento, la notificación se envía en fan-out a todas las URLs activas registradas para ese eventType. Cada URL tiene su propia entrega, reintento e idempotencia — un fallo en una URL no afecta a las demás.

Al volver a registrar una URL existente, omitir headers o version preserva los valores anteriores. Enviar el campo explícitamente reemplaza el valor anterior de ese campo — los demás campos omitidos permanecen preservados.

Códigos de Error

Código	Descripción
400	URL inválida (no HTTPS), tipo de evento inválido, más de 5 encabezados o más de 3 URLs activas por evento
401	Token no proporcionado o inválido
404	Cuenta no encontrada
500	Error interno al configurar webhook

Configurar Múltiples Eventos

Para recibir notificaciones de múltiples tipos de eventos, realice una llamada por cada tipo:

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

for (const eventType of eventTypes) {
  await fetch('https://api-pay.brasilbitco.in/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' },
      ],
    }),
  });
}

Puede usar la misma URL para todos los tipos de eventos y diferenciar por el campo type en el payload del webhook.

Configurar Webhooks vía API

Descripción General

Endpoint

Autenticación

Parámetros

Ejemplo de Solicitud

Ejemplo de Respuesta

Múltiples URLs por Evento

Códigos de Error

Configurar Múltiples Eventos

Próximos Pasos

Estructura del Payload

Implementación

Reenviar Webhook

Webhook Cash-In

Webhooks MED

En esta página