Webhooks
IntroduçãoCopied!
Os webhooks permitem que você receba notificações em tempo real sobre eventos relacionados às transações em sua aplicação. Existem duas maneiras de configurar webhooks no sistema Pay2Win:
-
Configurando um webhook dedicado através do endpoint de criação de webhooks
-
Utilizando o campo
postbackUrl
ao criar uma transação
Vamos explorar cada uma dessas abordagens em detalhes.
Configurando Webhook DedicadoCopied!
Para criar um webhook dedicado, você pode utilizar o seguinte endpoint:
POST /webhook
Corpo da requisição:
{
"url": "https://seu-dominio.com/webhook",
"token": "49e926f4-d4a1-432c-8671-1ecfbb4e8dbf" // Opcional
}
Parâmetros:
-
url
(obrigatório): URL que receberá as notificações (deve ser uma URL válida) -
token
(opcional): Token de verificação que será enviado no cabeçalho (X-Webhook-Token
) das requisições para garantir a autenticidade
Resposta:
Em caso de sucesso, você receberá:
{
"message": "Webhook criado com sucesso",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"url": "https://seu-dominio.com/webhook"
}
}
Removendo um Webhook
Para remover um webhook configurado, utilize:
DELETE /webhook/:id
Onde :id
é o identificado único do webhook que você deseja remover.
Configurando Webhook via postbackUrlCopied!
Ao criar uma transação, você pode especificar uma URL de postback que receberá notificações sobre mudanças no status desta transação específica.
Como usar
Ao criar uma transação, inclua o parâmetro postbackUrl
no corpo da requisição:
{
"paymentMethod": "credit_card",
"value": 10000,
"postbackUrl": "https://seu-dominio.com/notificacoes",
// outros parâmetros da transação...
}
Esta abordagem é útil quando você quer receber notificações apenas para transações específicas ou quando deseja direcionar notificações para endpoints diferentes com base no contexto da transação.
Formato das NotificaçõesCopied!
Quando ocorre um evento (como uma mudança no status da transação), o sistema envia uma notificação para a URL configurada com o seguinte formato:
{
"type": "transaction",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "paid",
"metadata": {
"customField1": "valor1",
"customField2": "valor2"
},
"installments": 1,
"dueAt": "2023-12-01T14:30:00.000Z",
"releaseAt": "2023-12-03T14:30:00.000Z",
"paidAt": "2023-12-01T14:35:00.000Z",
"externalReference": "pedido-123",
"isTraceable": false,
"paymentMethod": "credit_card",
"amount": 10000,
"items": [
{
"title": "Produto exemplo",
"externalRef": "SKU123",
"unitPrice": 5000,
"quantity": 2
}
],
"discounts": [
{
"identification": "PROMO10",
"amount": 1000
}
]
}
}
Tratamento de EventosCopied!
Ao receber um webhook, sua aplicação deve:
-
Validar a autenticidade da requisição (se um token foi configurado)
-
Processar a informação conforme necessário
-
Retornar um código de status HTTP 200 para confirmar o recebimento
Se o sistema não receber uma resposta 200, ele tentará reenviar a notificação algumas vezes.
Considerações ImportantesCopied!
-
Certifique-se de que sua URL de webhook esteja disponível publicamente
-
Implemente validação adequada para garantir a segurança de seus endpoints
-
O processamento deve ser rápido - se precisar de processamento demorado, armazene a notificação e processe-a de forma assíncrona
-
Considere adicionar logging para facilitar a depuração de webhooks
Exemplo de Implementação de ReceptorCopied!
Abaixo está um exemplo simples de como implementar um receptor de webhook em uma aplicação Express:
app.post('/webhook', (req, res) => {
// Verificar autenticidade (se necessário)
const token = req.headers['x-webhook-token'];
// Processar os dados da transação
const { type, data } = req.body;
if (type === 'transaction') {
// Atualizar status da transação no seu sistema
updateOrderStatus(data.externalReference, data.status);
// Registrar para fins de auditoria
console.log(`Transação ${data.id} atualizada para ${data.status}`);
}
// Confirmar recebimento
res.status(200).send({ received: true });
});
Com este guia, você deve estar pronto para implementar e gerenciar webhooks em sua integração com a Pay2Win, permitindo que sua aplicação receba atualizações em tempo real sobre as transações processadas.