Skip to main content
Pense nos webhooks como “mensagens enviadas pela Upay para o seu sistema”, sem que você precise ficar consultando a API o tempo todo.

​
Por que usar webhooks?

Sem webhooks, sua aplicação teria que perguntar para a API a cada segundo:
“Essa transação já foi confirmada?”
Com webhooks, a Upay avisa você imediatamente:
“A transação foi confirmada. Aqui estão os dados.”
Assim você pode:
  • Atualizar o status de um pedido
  • Liberar acesso a um produto digital
  • Enviar e-mails automáticos de confirmação
  • Registrar movimentações financeiras
Tudo isso de forma automática, sem fazer seu cliente esperar.

​
Como funciona na prática?

  1. Você cria um endpoint no seu sistema Ex.: https://meusite.com.br/webhooks/upay
  2. Você cadastra esse endpoint via API ou Dashboard
  3. Sempre que algo importante acontece, como uma transação paga:
    • A Upay envia um POST para a sua URL
    • O POST contém o evento (ex: transaction.completed)
    • Seu sistema processa esse evento e responde 200 OK

​
Segurança dos webhooks

Toda requisição enviada inclui dois mecanismos de segurança:

Assinatura HMAC

Cada webhook inclui o header X-Webhook-Signature: sha256=... gerado com HMAC-SHA256. Sempre valide essa assinatura antes de processar o evento — garante que a requisição foi enviada pela Upay e que o corpo não foi alterado.

Headers de identificação

Além da assinatura, cada entrega inclui:
  • X-Webhook-Event — tipo do evento (ex: transaction.completed)
  • X-Webhook-Delivery — UUID único da entrega
  • User-Agent: UPAY-Webhook/1.0

​
Validação da assinatura

import crypto from 'crypto';

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const expected  = `sha256=${crypto
    .createHmac('sha256', process.env.UPAY_WEBHOOK_SECRET!)
    .update(req.body)
    .digest('hex')}`;

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const event = JSON.parse(req.body.toString());
  // processar event.type ...
  res.json({ received: true });
});

​
Estrutura do payload

Todos os webhooks compartilham o mesmo envelope: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "transaction.completed",
  "timestamp": "2026-04-08T12:00:00.000Z",
  "data": { ... },
  "subscription": {
    "id": "whs_abc123",
    "url": "https://meusite.com.br/webhooks/upay"
  }
}

​
Eventos suportados

EventoQuando é disparado
transaction.createdNova transação criada
transaction.completedPagamento confirmado
transaction.failedPagamento falhou
transaction.updatedStatus da transação atualizado
payment_link.createdNovo link de pagamento criado
payment_link.updatedLink de pagamento atualizado
balance.updatedSaldo da conta alterado

​
Payloads por evento

​
Transações

Disparado quando um pagamento é confirmado.
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "transaction.completed",
  "timestamp": "2026-04-08T12:00:00.000Z",
  "data": {
    "transactionId": "txn_abc123",
    "status": "PAID",
    "amount": 9900,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "paidAt": "2026-04-08T12:00:00.000Z"
  },
  "subscription": {
    "id": "whs_abc123",
    "url": "https://meusite.com.br/webhooks/upay"
  }
}

​
Criando uma assinatura de webhook

1

Crie uma assinatura via API

curl --request POST \
  --url https://upay-sistema-api.onrender.com/api/webhooks/subscriptions \
  --header 'Authorization: Bearer SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://meusite.com.br/webhooks/upay",
    "events": ["transaction.completed", "transaction.failed"]
  }'
2

Implemente o endpoint

Seu endpoint deve responder 200 OK em até 10 segundos. Respostas fora desse prazo são tratadas como falha e a entrega será retentada automaticamente.
3

Valide a assinatura

Use o header X-Webhook-Signature para verificar que a requisição veio da Upay. Veja os exemplos de código acima.

​
Boas práticas

  • Use HTTPS em todos os endpoints de webhook
  • Valide sempre a assinatura HMAC antes de processar
  • Registre cada evento recebido — processe cada um uma única vez (idempotência)
  • Responda 200 OK somente após concluir o processamento
  • Implemente retentativas com idempotência no seu sistema
  • Não valide o schema completo do payload — mudanças futuras não devem quebrar seu endpoint

Precisa de ajuda?

Nossa equipe está disponível para ajudar. Entre em contato: suporte@upaybr.com