Skip to main content

​
O que são Webhooks?

Os Webhooks PIX permitem que você receba notificações em tempo real quando o status de uma transação PIX muda. Em vez de fazer polling constantemente na API, seu sistema é notificado automaticamente quando eventos importantes ocorrem.
Webhooks são a forma recomendada de acompanhar o status das transações. Eles reduzem a latência e o consumo de recursos comparado ao polling.

​
Características

  • Notificações em tempo real
  • Suporte a 4 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out)
  • Retentativas automáticas em caso de falha
  • Autenticação via Basic Auth
  • Payload padronizado em JSON

​
Eventos Disponíveis

CashIn

Recebimento PIX confirmado (CREDIT)

CashOut

Envio PIX confirmado (DEBIT)

CashInReversal

Estorno de recebimento (DEBIT)

CashOutReversal

Devolução de envio recebida (CREDIT)
EventoeventmovementTypeDescrição
PIX InCashInCREDITRecebimento PIX confirmado
PIX OutCashOutDEBITEnvio PIX confirmado
Refund InCashInReversalDEBITEstorno de recebimento (devolução iniciada por você)
Refund OutCashOutReversalCREDITDevolução de envio (devolução recebida)

​
Configuração do Endpoint

Para receber webhooks, você precisa:
1

Configurar URL de Webhook

Entre em contato com o suporte da Avista para configurar a URL do seu endpoint de webhook.
2

Implementar Endpoint

Crie um endpoint HTTPS que aceite requisições POST e retorne HTTP 200 rapidamente.
3

Validar Autenticação

Configure a validação do header de autenticação Basic Auth.

​
Requisitos Técnicos

RequisitoDescrição
ProtocoloHTTPS obrigatório
MétodoPOST
TimeoutResponder em até 10 segundos
ResponseHTTP 200 OK
Content-Typeapplication/json
Se seu endpoint não responder com HTTP 200 dentro de 10 segundos, o webhook será considerado como falha e será retentado.

​
Autenticação Basic Auth

Os webhooks são enviados com autenticação Basic Auth no header: 
Authorization: Basic base64(username:password)

// Node.js/Express - Validação
app.post('/webhooks/pix', (req, res) => {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Basic ')) {
    return res.status(401).send('Unauthorized');
  }

  const base64Credentials = authHeader.split(' ')[1];
  const credentials = Buffer.from(base64Credentials, 'base64').toString('ascii');
  const [username, password] = credentials.split(':');

  if (username !== process.env.WEBHOOK_USER || password !== process.env.WEBHOOK_PASS) {
    return res.status(401).send('Unauthorized');
  }

  // Processar webhook...
  res.status(200).json({ acknowledged: true });
});

​
Estrutura Base do Payload

Todos os webhooks compartilham uma estrutura base comum: 
{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "6d94e3ce-5a10-4fbe-a01c-f03c743a6608",
  "externalId": "PIX-5482123298-EJUYFSMU1UU",
  "endToEndId": "E00416968202512111942rjzxxzSSTD9",
  "pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
  "feeAmount": 0.01,
  "originalAmount": 0.5,
  "finalAmount": 0.49,
  "processingDate": "2025-12-11T19:42:04.080Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {}
}
​
event
string
required
Tipo do evento.Valores possíveis: CashIn, CashOut, CashInReversal, CashOutReversal
​
status
string
required
Status da transação.Valores possíveis: PENDING, CONFIRMED, ERROR
​
transactionType
string
required
Tipo de transação. Sempre PIX para webhooks PIX.
​
movementType
string
required
Tipo de movimento na conta.
  • CREDIT: Entrada de recursos (recebimento ou devolução recebida)
  • DEBIT: Saída de recursos (envio ou estorno)
​
transactionId
string
required
UUID único da transação na Avista.Exemplo: "6d94e3ce-5a10-4fbe-a01c-f03c743a6608"
​
endToEndId
string
required
ID End-to-End gerado pelo Banco Central para rastreamento.Exemplo: "E00416968202512111942rjzxxzSSTD9"
​
processingDate
string
required
Data e hora do processamento (ISO 8601 UTC).Exemplo: "2025-12-11T19:42:04.080Z"
​
feeAmount
number
required
Taxa cobrada pela transação em reais (BRL).Exemplo: 0.01
​
originalAmount
number
required
Valor original da transação em reais (BRL).Exemplo: 0.50
​
finalAmount
number
required
Valor final após aplicação de taxas.
  • Para CREDIT: originalAmount - feeAmount
  • Para DEBIT: originalAmount + feeAmount
​
externalId
string
ID externo fornecido na criação da transação.Exemplo: "PIX-5482123298-EJUYFSMU1UU"
​
pixKey
string
Chave PIX utilizada na transação (CPF, CNPJ, email, telefone ou chave aleatória).
​
errorCode
string
Código de erro quando status é ERROR. Nulo se sucesso.
​
errorMessage
string
Mensagem de erro descritiva. Nulo se sucesso.
​
metadata
object
Metadados adicionais específicos do evento.

​
Próximos Passos

CashIn

Detalhes do evento de recebimento

CashOut

Detalhes do evento de envio

CashInReversal

Detalhes do evento de estorno

CashOutReversal

Detalhes do evento de devolução