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

URL de retorno na criação da transação (`postbackUrl`)

Ao criar uma transação pela API, você também pode informar uma postbackUrl. Ela reTRANSACTION_CREATED_OR_UPDATED, a cada mudança de status daquela transação, emparalelo com os webhooks cadastrados na plataforma. Se você usar os dois, recebe nos dois.

💡 A postbackUrl recebe só o evento de transação. Para receber as mudanças de status de entrega, cadastre um webhook do evento TRANSACTION_TRACKING_STATUS_CHANGED na plataforma.

Eventos disponíveis

Atualmente, a Bestfy dispara webhooks para os seguintes eventos:

Evento	Descrição
`TRANSACTION_CREATED_OR_UPDATED`	Disparado quando uma transação é criada ou tem seu status atualizado
`TRANSACTION_TRACKING_STATUS_CHANGED`	Disparado quando o rastreio do pedido é crus de entrega depois

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

Transações PIX e boleto geram um evento na criação, já com o status PENDING: a cobrança foi emitida e está aguardando pagamento.

{
  "companyId": "uuid-da-empresa",
  "transactionId": "uuid-da-transacao",
  "status": "PENDING",
  "paymentMethod": "PIX",
  "customerEmail": "johndoe@email.com"
}

💡 Transações de cartão de crédito não geram evento na criação. O primeiro evento de um cartão já é o desfecho (PAID ou REJECTED). Quando o cartão é recusado na hora, a recusa vem na própria
resposta da criação e nenhum evento é enviado.

Quando a transação tem o status atualizado

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

{
  "companyId": "uuid-da-empresa",
  "transactionId": "uuid-da-transacao",
  "status": "PAID",
  "paymentMethod": "PIX",
  "customerEmail": "johndoe@email.com",
  "customer": {
    "name": "John Doe",
    "email": "johndoe@email.com",
    "phone": "5511999999999",
    "cpfCnpj": "12345678900"
  },
  "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`)
`paymentMethod`	✅	✅	Meio de pagamento da transação
`customerEmail`	✅	✅	E-mail do cliente
`customer`	❌	✅	Dados do cliente
`pixEndToEndId`	❌	⚠️	ID end-to-end do PIX (somente quando pagamento PIX é confirmado)
`paymentConfirmedAt`	❌	⚠️	Data/hora de confirmação (somente q

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 abaixo)
`paymentMethod`	`string`	`PIX`, `CREDIT_CARD` ou `BOLETO`
`customerEmail`	`string`	E-mail do cliente
`customer`	`object`	`name`, `email`, `phone` e `cpfCnpj`; e, quando informado, o endereço (`postalCode`, `neighborhood`, `city`, `state`, `streetAddress`, `streetNumber`, `complement`)
`pixEndToEndId`	`string`	Identificador end-to-end do PIX (apenas para pagamentos PIX)
`paymentConfirmedAt`	`string`	Data/hora de confirmação do pagamento (formato ISO 8601)

Evento de status de entrega (`TRANSACTION_TRACKING_STATUS_CHANGED`)

Disparado quando o rastreio de um pedido com produto físico é criado e a cada mudança do status de entrega depois disso. Correções só do código de rastreio ou da transportadora não geram evento.

O corpo traz o novo status em trackingStatus e o anterior em previousTrackingStatus (null quando o rastreio acabou de ser criado), além do código de rastreio, da transportadora, do status de
pagamento da transação, dos dados do cliente e dos itens do pedido.

{
  "companyId": "uuid-da-empresa",
  "transactionId": "uuid-da-transacao",
  "transactionStatus": "PAID",
  "trackingNumber": "BR123456789BR",
  "service": "SEDEX",
  "trackingStatus": "IN_TRANSIT",
  "previousTrackingStatus": "SHIPPED",
  "changedAt": "2025-12-18T09:15:00.000Z",
  "customer": { "name": "John Doe", "email": "johndoe@email.com" },
  "cartItems": [
    { "productId": "uuid-do-produto", "productName": "Camiseta Básica", "productQuantity": 2 }
  ]
}

Status de entrega	Descrição
`PENDING_SHIPMENT`	Aguardando envio
`SEPARATING`	Em separação
`SHIPPED`	Enviado
`IN_TRANSIT`	Em trânsito
`OUT_FOR_DELIVERY`	Saiu para entrega
`DELIVERED`	Entregue
`RETURNED`	Devolvido
`LOST`	Extraviado

💡 Eventos de entrega podem chegar fora de ordem. Use changedAt para descartar o mais antigo.

Status da transação

O campo status segue o ciclo de vida descrito em Status de Pagamento na Bestfy. Lá estão todos os valores possíveis, quando cada um
é atribuído e quais mudanças de status podem acontecer.

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 confirma

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

Reconciliação: Cada evento é enviado uma única vez, sem nova tentativa (veja

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

Entrega dos eventos

Cada mudança de status gera um único evento, sem nova tentativa. Se a sua URL estiver fora do ar, responder com erro ou demorar mais de 5 segundos, o evento não é reenviado. Para reconciliar, consulte a transação em GET /transaction/{financialTransactionId}, que é a fonte da verdade.

Aceite PAID depois de EXPIRED ou REJECTED. É um pagamento tardio, honrade Pagamento naBestfy](https://docs.bestfy.io/status-de-pagamento-na-bestfy-2108801m0)).

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#

URL de retorno na criação da transação (postbackUrl)#

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#

Evento de status de entrega (TRANSACTION_TRACKING_STATUS_CHANGED)#

Status da transação#

Exemplo de recebimento#

Boas práticas#

Entrega dos eventos#

Erros comuns#