Configurar webhook de la cuenta

POST /api/webhooks

POST https://api.avista.global/api/webhooks

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

Configura o actualiza la URL del webhook para un tipo de evento específico. Si ya existe un webhook para el mismo tipo de evento, se actualizará (comportamiento upsert).

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.avista.global/api/webhooks" \
  -H "Authorization: Bearer $AVISTA_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.avista.global/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.AVISTA_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.avista.global/api/webhooks',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_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.avista.global/api/webhooks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_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.avista.global/api/webhooks"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_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, etc.)
401	Token faltante o inválido
404	Cuenta no encontrada
500	Error interno al configurar el webhook