Webhooks e Notificações

Receba notificações em tempo real sobre pagamentos, splits e eventos da conta.
Resumo Rápido

Configure uma URL de callback no painel da AjnaPay para receber notificações HTTP POST sobre eventos importantes. Seu servidor deve responder com status 200 para confirmar o recebimento.

1. Configurando Webhooks

Acesse o painel da AjnaPay e configure a URL de webhook:

  1. Vá em Configurações → Webhooks
  2. Clique em "Adicionar Webhook"
  3. Insira a URL do seu endpoint (deve ser HTTPS)
  4. Selecione os eventos que deseja receber
  5. Salve a configuração

2. Eventos Disponíveis

Evento Descrição Payload Principal
payment.received Pagamento PIX recebido deposit_id, amount, status
payment.sent Pagamento PIX enviado request_payment_id, amount, status
subscription.created Nova assinatura criada subscription_id, amount, frequency
subscription.charged Cobrança recorrente realizada subscription_id, charge_id, amount
subscription.failed Cobrança recorrente falhou subscription_id, error_message
split.processed Split distribuído deposit_id, account_id, amount
balance.updated Saldo atualizado account_id, balance, currency

3. Estrutura do Payload

Todos os webhooks seguem o mesmo formato:

Payload Padrão 
{
  "event": "payment.received",
  "timestamp": "2026-07-21T10:30:00Z",
  "data": {
    "id": "uuid-do-evento",
    "type": "deposit",
    "status": "completed",
    "amount": "150.00",
    "currency": "BRL",
    "account_id": "uuid-da-conta",
    "metadata": {
      "description": "Pagamento de serviço"
    }
  }
}

4. Implementando o Endpoint

Exemplo com PHP (Laravel) 
// routes/web.php
Route::post('/webhooks/ajnapay', function (Request $request) {
    $event = $request->input('event');
    $data = $request->input('data');

    // Processar o evento
    match($event) {
        'payment.received' => handlePaymentReceived($data),
        'subscription.charged' => handleSubscriptionCharged($data),
        'balance.updated' => handleBalanceUpdated($data),
        default => Log::info('Evento desconhecido: ' . $event),
    };

    // Retornar 200 para confirmar recebimento
    return response()->json(['status' => 'ok'], 200);
});
Exemplo com Node.js (Express) 
app.post('/webhooks/ajnapay', (req, res) => {
    const { event, data } = req.body;

    switch(event) {
        case 'payment.received':
            handlePaymentReceived(data);
            break;
        case 'subscription.charged':
            handleSubscriptionCharged(data);
            break;
        case 'balance.updated':
            handleBalanceUpdated(data);
            break;
    }

    res.status(200).json({ status: 'ok' });
});

5. Boas Práticas

  • Valide a origem: Verifique se o webhook vem da AjnaPay (IP whitelist ou signature)
  • Responda rápido: Retorne 200 imediatamente e processe em background
  • Idempotência: Use o event ID para evitar processamento duplicado
  • Logs: Registre todos os webhooks recebidos para debugging
  • Retry: A AjnaPay tenta reenviar webhooks falhos até 3 vezes

6. Testando Webhooks

Use ferramentas como webhook.site ou ngrok para testar webhooks em desenvolvimento.

Anterior: Enviando PIX Próximo: Saldos e Extrato