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 la URL recién configurada.
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
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
Tipo de evento para el que desea recibir notificaciones.
Valores posibles:
cash_in- PIX recibidocash_out- PIX enviadorefund_in- Devolución de pago recibido (devolución solicitada)refund_out- Devolución recibidamed_created- MED (Mecanismo Especial de Devolución) abierto contra una transacción recibidamed_accepted- Solicitud de devolución MED aprobadamed_rejected- Solicitud de devolución MED rechazada
Encabezados personalizados para la autenticación de su endpoint (máximo 5).
Cada elemento debe tener:
key: Nombre del encabezadovalue: 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.avista.global/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.avista.global/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.avista.global/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"
}Comportamiento Upsert
Si ya existe un webhook configurado para el mismo eventType, será actualizado con la nueva URL y encabezados. No se crea un webhook duplicado.
Al actualizar un webhook existente, los encabezados anteriores son reemplazados por los nuevos. Si no envía encabezados, los encabezados anteriores serán eliminados.
Códigos de Error
| Código | Descripción |
|---|---|
| 400 | URL inválida (no HTTPS), tipo de evento inválido o más de 5 encabezados |
| 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.avista.global/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.
Próximos Pasos
Estructura del Payload
Comprenda la estructura de los webhooks recibidos
Implementación
Ejemplos de código para procesar webhooks
Reenviar Webhook
Reenvíe webhooks perdidos o para pruebas
Webhook Cash-In
Detalles del webhook de PIX recibido
Webhooks MED
Recibe notificaciones sobre eventos MED (Mecanismo Especial de Devolución)