Webhook

O que são Webhooks?

Webhooks são notificações HTTP enviadas automaticamente pelo RecebeAqui para o seu sistema sempre que eventos importantes acontecem em sua conta.

Eventos notificados:

• Pagamentos aprovados: Quando um cliente efetua um pagamento com sucesso

Como Cadastrar um Webhook

Para configurar webhooks em sua conta RecebeAqui, siga os passos abaixo:

1. Faça login na sua conta RecebeAqui
2. Acesse a área de API no seu Perfil
3. Preencha a URL do webhook no campo indicado
4. Clique em Salvar para ativar as notificações

Estrutura do Payload

Quando um evento ocorre, o RecebeAqui enviará uma requisição POST para sua URL com o seguinte formato JSON:

{
  "EventType": "pagamento_aprovado",
  "EventDate": "2024-01-15 11:47:02.273",
  "Payment": {
    "Id": "b8c1f3a2-9d4e-4f6c-91e5-2a8f1f0b9e21",
    "PaymentType": "CREDITO",
    "PaymentDate": "2024-01-15 11:47:02.273",
    "PaidBy": "Cliente Teste",
    "AmountPaid": 99.99,
    "Installments": 1,
    "Status": "ATIVA",
    "CardType": "**** **** **** 1234",
    "CardBrand": "VISA"
  }
}

Implementando seu Endpoint

Seu endpoint deve aceitar requisições POST e retornar status HTTP 2xx para indicar sucesso. Exemplo de implementação:

• C#
• PHP
• Node.js

[HttpPost("webhook/pagamento")]
public IActionResult ReceberWebhook([FromBody] WebhookPayload payload)
{
    try
    {
        // Processar o pagamento recebido
        var payment = payload.Payment;
        
        // Sua lógica de negócio aqui
        ProcessarPagamentoAprovado(payment);
        
        return Ok();
    }
    catch (Exception)
    {
        // Retornar erro fará o sistema tentar novamente (até 3x)
        return StatusCode(500, "Erro interno");
    }
}

<?php
// webhook.php
header('Content-Type: application/json');

$payload = json_decode(file_get_contents('php://input'), true);

try {
    if ($payload['EventType'] === 'pagamento_aprovado') {
        $payment = $payload['Payment'];
        processarPagamento($payment);
        http_response_code(200);
        echo json_encode(['status' => 'success']);
    }
} catch (Exception $e) {
    http_response_code(500);
    echo json_encode(['error' => $e->getMessage()]);
}
?>

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/pagamento', (req, res) => {
    try {
        const payload = req.body;
        if (payload.EventType === 'pagamento_aprovado') {
            const payment = payload.Payment;
            processarPagamento(payment);
            res.status(200).json({ status: 'success' });
        }
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

app.listen(3000);

Política de Tentativas

O sistema de webhooks do RecebeAqui possui as seguintes características:

• Máximo 3 tentativas de envio por webhook
• Timeout de 30 segundos por tentativa
• Sucesso: qualquer resposta HTTP 2xx (200, 201, 204, etc.)
• Retry: qualquer resposta diferente de 2xx ou timeout
• Finalização: após sucesso ou 3 tentativas falhadas

Segurança

Para garantir a segurança dos webhooks:

• Use HTTPS em sua URL de webhook
• Valide sempre os dados recebidos
• Implemente verificação de origem se necessário
• Mantenha logs dos webhooks recebidos