Skip to main content
Os webhooks permitem que sua aplicação seja notificada automaticamente, em tempo real, sobre eventos relevantes na AobaPay. Isso elimina a necessidade de consultas manuais à API, garantindo mais agilidade e consistência em seus processos.

​
Gerenciando Webhooks

Você pode gerenciar seus webhooks diretamente pelo dashboard da AobaPay. É possível:
  • Listar todos os webhooks ativos
  • Criar novos webhooks conforme sua necessidade
  • Desativar webhooks que não serão mais utilizados

​
Criando Webhooks

Boas práticas de segurança

  • Utilize um secret exclusivo para cada webhook
  • Valide a assinatura de todas as requisições recebidas
  • Configure apenas URLs HTTPS para maior segurança
  • Implemente lógica de retry para lidar com falhas temporárias

​
Como criar seu Webhook

Siga estes passos no dashboard da AobaPay:
1

Acesse a seção de Webhooks

Interface da plataforma AobaPay mostrando a seção de webhooks

Navegue até a seção Integrar e clique em Webhooks

Inicie a configuração de um novo webhook
2

Inicie a criação

Formulário de criação de webhook

Clique em 'Criar'

Você será direcionado ao formulário de configuração
3

Configure seu Webhook

Preencha os campos obrigatórios:

  • Nome → Identificador do webhook (ex.: “Pagamentos Aprovados”)
  • URL → Endpoint HTTPS que receberá as notificações
  • Assinatura → Secret usado para validação das requisições
  • Status → Defina se o webhook ficará ativo ou inativo

​
Protegendo suas requisições

Cada notificação enviada inclui o secret configurado, que deve ser validado pela sua aplicação. Isso garante que apenas chamadas legítimas da AobaPay sejam processadas.

​
Exemplo de URL de Webhook

  • URL base configurada no dashboard:
https://meusite.com/webhook/aobapay
  • Chamadas realizadas pela AobaPay incluirão o header de assinatura com o secret:
signature: seu_secret_configurado

​
Exemplo de Implementação

// Exemplo de validação de webhook com Node.js/Express
app.post('/webhook/aobapay', (req, res) => {
  const signature = req.headers['signature'];

  if (signature !== process.env.WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Invalid webhook signature' });
  }

  // Processa o evento recebido
  const event = req.body;
  console.log('Webhook recebido:', event);

  res.status(200).json({ received: true });
});

​
Eventos Suportados

Atualmente, suportamos os seguintes eventos:

​
EVENT:CHARGE_PAID

Este evento é disparado quando um pagamento é confirmado: 
{
  "event": "EVENT:CHARGE_PAID",
  "data": {
    "id": "ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "externalID": null,
    "brCode": "00020101021226810014br.gov.bcb.pix255..",
    "brCodeImageUrl": "https://api.aobapay.com/v1/qrcode/ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "amount": 300,
    "expiration": "300",
    "fee": 78,
    "expiresAt": "2025-09-16 11:43:30",
    "status": "PAID",
    "customer": {
      "id": "cus_2352001f-43da-4875-b4c0-cc6350d3891e",
      "name": "Brendo Oliveira",
      "document": "123.456.789.01",
      "email": "[email protected]",
      "phone": "(15) 99799-1010"
    }
  }
}

​
EVENT:CHARGE_EXPIRED

Este evento é disparado quando uma cobrança é expirada 
{
  "event": "EVENT:CHARGE_EXPIRED",
  "data": {
    "id": "ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "externalID": null,
    "brCode": "00020101021226810014br.gov.bcb.pix255..",
    "brCodeImageUrl": "https://api.aobapay.com/v1/qrcode/ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "amount": 300,
    "expiration": "300",
    "fee": 78,
    "expiresAt": "2025-09-16 11:43:30",
    "status": "EXPIRED",
    "customer": {
      "id": "cus_2352001f-43da-4875-b4c0-cc6350d3891e",
      "name": "Brendo Oliveira",
      "document": "123.456.789.01",
      "email": "[email protected]",
      "phone": "(15) 99799-1010"
    }
  }
}

​
EVENT:CHARGE_REFUND

Este evento é disparado quando uma cobrança é extornada 
{
  "event": "EVENT:CHARGE_REFUND",
  "data": {
    "id": "ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "externalID": null,
    "brCode": "00020101021226810014br.gov.bcb.pix..",
    "brCodeImageUrl": "https://api.aobapay.com/v1/qrcode/ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "amount": 250,
    "expiration": "300",
    "fee": 78,
    "expiresAt": "2025-09-16 11:43:30",
    "status": "REFUNDED",
    "customer": {
      "id": "cus_2352001f-43da-4875-b4c0-cc6350d3891e",
      "name": "Brendo Otavio",
      "document": "490.464.828-55",
      "email": "[email protected]",
      "phone": "(15) 99787-6029"
    }
  }
}

​
EVENT:CASH_OUT

Este evento é disparado quando uma cobrança é extornada 
{
  "event": "EVENT:CASH_OUT",
  "data": {
    "id": "wdl_47d56145-870e-4240-83a4-c0199308278b",
    "externalID": "123-SAQUE",
    "amount": 200,
    "comment": "PAGAMENTO",
    "status": "DONE",
    "destination": {
      "name": "BRENDO OTAVIO DE OLIVEIRA SANTOS",
      "bankName": "BCO SANTANDER (BRASIL) S.A.",
      "pikKey": "[email protected]",
      "pixKeyType": "EMAIL",
      "account": "00000000000000000",
      "branch": "0000"
    },
    "createdAt": "2025-09-17 15:59:07",
    "updatedAt": "2025-09-17 15:59:10"
  }
}

​
EVENT:MED_CREATED

Este evento é disparado quando uma Disputa/Med é criada 
{
  "event": "EVENT:MED_CREATED",
  "data": {
    "id": "ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "externalID": null,
    "endToEndId": "8129812-189asnk1y1-1289aisn-1-2",
    "amount": 200,
    "name": "Sr Fulano",
    "email": "[email protected]",
    "status": "OPENED",
    "disputeReason": "Will me enganou!",
    "createdAt": "2025-09-17 15:59:07",
    "updatedAt": "2025-09-17 15:59:10"
  }
}

​
EVENT:MED_REJECTED

Este evento é disparado quando uma Disputa/Med é Rejeitada e Favorável a empresa. 
{
  "event": "EVENT:MED_REJECTED",
  "data": {
    "id": "ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "externalID": null,
    "endToEndId": "8129812-189asnk1y1-1289aisn-1-2",
    "amount": 200,
    "name": "Sr Fulano",
    "email": "[email protected]",
    "status": "REJECTED",
    "disputeReason": "Will me enganou!",
    "createdAt": "2025-09-17 15:59:07",
    "updatedAt": "2025-09-17 15:59:10"
  }
}

​
EVENT:MED_CANCELLED

Este evento é disparado quando uma Disputa/Med Cancelado 
{
  "event": "EVENT:MED_CANCELLED",
  "data": {
    "id": "ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "externalID": null,
    "endToEndId": "8129812-189asnk1y1-1289aisn-1-2",
    "amount": 200,
    "name": "Sr Fulano",
    "email": "[email protected]",
    "status": "CANCELLED",
    "disputeReason": "Will me enganou!",
    "createdAt": "2025-09-17 15:59:07",
    "updatedAt": "2025-09-17 15:59:10"
  }
}

​
EVENT:MED_ACCEPTED

Este evento é disparado quando uma Disputa/Med Aceito e Favorável ao cliente 
{
  "event": "EVENT:MED_ACCEPTED",
  "data": {
    "id": "ch_abb6bc4f-f55d-45ff-8be2-8fdbde0cb8b8",
    "externalID": null,
    "endToEndId": "8129812-189asnk1y1-1289aisn-1-2",
    "amount": 200,
    "name": "Sr Fulano",
    "email": "[email protected]",
    "status": "ACCEPTED",
    "disputeReason": "Will me enganou!",
    "createdAt": "2025-09-17 15:59:07",
    "updatedAt": "2025-09-17 15:59:10"
  }
}

Nota Importante

  • Todos os valores monetários são expressos em centavos
  • O campo fee representa a taxa cobrada pela AobaPay
  • O campo event identifica o tipo de evento recebido

Precisa de ajuda?

Nossa equipe está disponível para auxiliar na implementação de webhooks. Entre em contato pelo e-mail [email protected]