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 recibida
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.gateway.goforge.com.br/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.gateway.goforge.com.br/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.gateway.goforge.com.br/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'];
for (const eventType of eventTypes) {
await fetch('https://api.gateway.goforge.com.br/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.