Guia de ImplementaçãoReferencia

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:

  1. Configurando um webhook dedicado através do endpoint de criação de webhooks

  2. 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:

  1. Validar a autenticidade da requisição (se um token foi configurado)

  1. Processar a informação conforme necessário

  1. 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!

  1. Certifique-se de que sua URL de webhook esteja disponível publicamente

  2. Implemente validação adequada para garantir a segurança de seus endpoints

  3. O processamento deve ser rápido - se precisar de processamento demorado, armazene a notificação e processe-a de forma assíncrona

  4. 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.

© 2025 Pay2W