O que é um Webhook?

Um webhook é um mecanismo de comunicação entre sistemas que permite que a Bestfy envie notificações automáticas para uma URL da sua aplicação sempre que um evento importante ocorrer. Em vez de você precisar consultar nossa API repetidamente para verificar se algo mudou (polling), nós avisamos você instantaneamente.

Pense no webhook como um "aviso automático": quando uma transação é criada ou muda de status, a Bestfy faz uma requisição HTTP POST para a URL que você configurou, enviando os dados do evento no corpo da requisição.

Como configurar um Webhook

Para configurar um webhook na sua conta:

Acesse a plataforma da Bestfy

No menu lateral esquerdo, clique em Webhooks

Clique em Criar webhook

Preencha os campos:

URL: A URL do seu servidor que receberá as notificações (deve aceitar requisições POST)

Evento: Selecione o evento que deseja monitorar

Clique em Salvar

⚠️ Limite: Você pode cadastrar no máximo 3 webhooks por evento

Eventos disponíveis

Atualmente, a Bestfy dispara webhooks para o seguinte evento:

Evento	Descrição
`TRANSACTION_CREATED_OR_UPDATED`	Disparado quando uma transação é criada ou tem seu status atualizado

Payload do Webhook

Quando um evento ocorre, enviamos uma requisição POST para a sua URL. O conteúdo do payload varia conforme o momento do disparo.

Quando a transação é criada

Ao criar uma nova transação (via PIX, cartão de crédito, etc.), enviamos o payload mais simples:

{
  "companyId": "uuid-da-empresa",
  "transactionId": "uuid-da-transacao",
  "status": "PENDING"
}

💡 O status na criação é sempre PENDING, indicando que a transação foi gerada e está aguardando pagamento.

Quando a transação tem o status atualizado

Quando o status da transação muda (por exemplo, de PENDING para PAID), o payload inclui campos adicionais:

{
  "companyId": "uuid-da-empresa",
  "transactionId": "uuid-da-transacao",
  "status": "PAID",
  "pixEndToEndId": "E12345678202312171430abc123def456",
  "paymentConfirmedAt": "2025-12-17T14:30:00.000Z"
}

Comparativo dos campos

Campo	Criação	Atualização	Descrição
`companyId`	✅	✅	Identificador único da empresa
`transactionId`	✅	✅	Identificador único da transação
`status`	✅	✅	Status da transação (na criação é sempre `PENDING`)
`pixEndToEndId`	❌	⚠️	ID end-to-end do PIX (somente quando pagamento PIX é confirmado)
`paymentConfirmedAt`	❌	⚠️	Data/hora de confirmação (somente quando a transação for paga)

Descrição dos campos

Campo	Tipo	Descrição
`companyId`	`string`	Identificador único da empresa (UUID)
`transactionId`	`string`	Identificador único da transação financeira (UUID)
`status`	`string`	Status atual da transação (veja tabela abaixo)
`pixEndToEndId`	`string`	Identificador end-to-end do PIX (apenas para pagamentos PIX)
`paymentConfirmedAt`	`string`	Data/hora de confirmação do pagamento (formato ISO 8601)

Status da transação

O campo status pode conter os seguintes valores:

Status	Descrição
`PENDING`	Transação pendente, aguardando pagamento
`PAID`	Pagamento confirmado com sucesso
`CANCELED`	Transação cancelada
`EXPIRED`	Transação expirada (prazo de pagamento vencido)
`REFUNDED`	Valor estornado ao cliente
`UNDER_REVIEW`	Pagamento em análise
`REJECTED`	Pagamento rejeitado
`MED`	Mecanismo Especial de Devolução (PIX)
`UNKNOWN`	Status desconhecido

Exemplo de recebimento

Seu servidor deve estar preparado para receber requisições POST. Exemplo em Node.js/Express:

Boas práticas

Responda rapidamente: Retorne um status 2xx em até 5 segundos para confirmar o recebimento

Processamento assíncrono: Se precisar executar operações demoradas, salve o payload e processe em background

Idempotência: Prepare seu sistema para receber o mesmo evento mais de uma vez (webhooks podem ser reenviados)

Validação: Sempre valide o companyId para garantir que o evento pertence à sua conta

HTTPS: Use sempre URLs com HTTPS para garantir a segurança dos dados

Erros comuns

Código	Motivo
`400`	Limite de webhooks excedido (máximo 3 por evento)
`404`	Empresa não encontrada
`409`	URL já cadastrada para este evento
`500`	Erro interno

O que é um Webhook?

Como configurar um Webhook#

Eventos disponíveis#

Payload do Webhook#

Quando a transação é criada#

Quando a transação tem o status atualizado#

Comparativo dos campos#

Descrição dos campos#

Status da transação#

Exemplo de recebimento#

Boas práticas#

Erros comuns#