Visão Geral Webhooks permitem que você receba notificações HTTP automáticas quando eventos importantes ocorrem nos seus pagamentos. Configure a URL do webhook no dashboard para começar a receber eventos.
Eventos Disponíveis Evento Descrição payment.createdPagamento foi criado com sucesso payment.pendingPagamento está aguardando confirmação payment.confirmedPagamento foi confirmado payment.expiredPagamento expirou sem ser pago payment.cancelledPagamento foi cancelado payment.refundedPagamento foi reembolsado payment.failedFalha ao criar o pagamento no provedor
Estrutura do Payload Todos os webhooks seguem uma estrutura padrão:
{ "id" : "evt_550e8400-e29b-41d4-a716-446655440000" , "type" : "payment.confirmed" , "created" : 1706454600 , "data" : { "payment" : { // Dados do pagamento } } }
Campo Tipo Descrição idstring Identificador único do evento typestring Tipo do evento (ex: payment.confirmed) creatednumber Timestamp Unix em segundos dataobject Dados específicos do evento
Exemplos de Payload
Enviado imediatamente após a criação de um pagamento. { "id" : "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "type" : "payment.created" , "created" : 1706454600 , "data" : { "payment" : { "id" : "pay_123456" , "externalId" : "pedido-123" , "amount" : 150.50 , "currency" : "BRL" , "description" : "Pagamento do Pedido #123" , "payerName" : "João Silva" , "payerDocument" : "12345678900" , "payerEmail" : "[email protected] " , "status" : "pending" , "provider" : "pague_dev" , "pixCopyPaste" : "00020126580014br.gov.bcb.pix..." , "expiresAt" : "2026-01-28T16:00:00.000Z" , "confirmedAt" : null , "isTest" : false , "metadata" : { "orderId" : "123" , "source" : "mobile" }, "createdAt" : "2026-01-28T15:00:00.000Z" , "updatedAt" : "2026-01-28T15:00:00.000Z" } } }
Enviado quando um pagamento PIX é confirmado. { "id" : "evt_b2c3d4e5-f6a7-8901-bcde-f12345678901" , "type" : "payment.confirmed" , "created" : 1706454900 , "data" : { "payment" : { "id" : "pay_123456" , "externalId" : "pedido-123" , "amount" : 150.50 , "currency" : "BRL" , "description" : "Pagamento do Pedido #123" , "payerName" : "João Silva" , "payerDocument" : "12345678900" , "payerEmail" : "[email protected] " , "status" : "confirmed" , "provider" : "pague_dev" , "pixCopyPaste" : "00020126580014br.gov.bcb.pix..." , "expiresAt" : "2026-01-28T16:00:00.000Z" , "confirmedAt" : "2026-01-28T15:05:00.000Z" , "isTest" : false , "metadata" : { "orderId" : "123" , "source" : "mobile" }, "createdAt" : "2026-01-28T15:00:00.000Z" , "updatedAt" : "2026-01-28T15:05:00.000Z" } } }
Enviado quando um pagamento expira sem ser pago. { "id" : "evt_c3d4e5f6-a7b8-9012-cdef-123456789012" , "type" : "payment.expired" , "created" : 1706458200 , "data" : { "payment" : { "id" : "pay_789012" , "externalId" : "pedido-456" , "amount" : 75.00 , "currency" : "BRL" , "description" : "Pagamento do Pedido #456" , "payerName" : "Maria Santos" , "payerDocument" : "98765432100" , "payerEmail" : "[email protected] " , "status" : "expired" , "provider" : "asaas" , "pixCopyPaste" : "00020126580014br.gov.bcb.pix..." , "expiresAt" : "2026-01-28T16:00:00.000Z" , "confirmedAt" : null , "isTest" : false , "metadata" : null , "createdAt" : "2026-01-28T15:00:00.000Z" , "updatedAt" : "2026-01-28T16:00:00.000Z" } } }
Enviado quando um pagamento é cancelado. { "id" : "evt_d4e5f6a7-b8c9-0123-def0-234567890123" , "type" : "payment.cancelled" , "created" : 1706455800 , "data" : { "payment" : { "id" : "pay_345678" , "externalId" : "pedido-789" , "amount" : 200.00 , "currency" : "BRL" , "description" : "Pagamento do Pedido #789" , "payerName" : "Carlos Oliveira" , "payerDocument" : "11122233344" , "payerEmail" : "[email protected] " , "status" : "cancelled" , "provider" : "pague_dev" , "pixCopyPaste" : null , "expiresAt" : "2026-01-28T16:00:00.000Z" , "confirmedAt" : null , "isTest" : false , "metadata" : null , "createdAt" : "2026-01-28T15:00:00.000Z" , "updatedAt" : "2026-01-28T15:10:00.000Z" } } }
Enviado quando um pagamento é reembolsado. { "id" : "evt_e5f6a7b8-c9d0-1234-ef01-345678901234" , "type" : "payment.refunded" , "created" : 1706458800 , "data" : { "payment" : { "id" : "pay_567890" , "externalId" : "pedido-321" , "amount" : 99.90 , "currency" : "BRL" , "description" : "Pagamento do Pedido #321" , "payerName" : "Ana Costa" , "payerDocument" : "55566677788" , "payerEmail" : "[email protected] " , "status" : "refunded" , "provider" : "asaas" , "pixCopyPaste" : "00020126580014br.gov.bcb.pix..." , "expiresAt" : "2026-01-28T16:00:00.000Z" , "confirmedAt" : "2026-01-28T15:05:00.000Z" , "isTest" : false , "metadata" : { "refundReason" : "customer_request" }, "createdAt" : "2026-01-28T15:00:00.000Z" , "updatedAt" : "2026-01-28T16:10:00.000Z" } } }
Enviado quando ocorre uma falha ao criar o pagamento no provedor. Este evento tem uma estrutura diferente dos demais. { "id" : "evt_f6a7b8c9-d0e1-2345-f012-456789012345" , "type" : "payment.failed" , "created" : 1706454600 , "data" : { "request" : { "amount" : 100.00 , "currency" : "BRL" , "description" : "Pagamento do Pedido #999" , "externalId" : "pedido-999" , "payerName" : "Pedro Lima" , "payerDocument" : "99988877766" , "payerEmail" : "[email protected] " , "provider" : "asaas" , "isTest" : false , "metadata" : null }, "error" : { "message" : "Invalid credentials provided" , "provider" : "asaas" } } }
Estrutura do Objeto Payment Campo Tipo Descrição idstring ID único do pagamento externalIdstring | null ID de referência externa amountnumber Valor em BRL (ex: 10.50) currencystring Moeda (sempre “BRL”) descriptionstring | null Descrição do pagamento payerNamestring | null Nome do pagador payerDocumentstring | null CPF ou CNPJ do pagador payerEmailstring | null E-mail do pagador statusstring Status: pending, confirmed, expired, cancelled, refunded providerstring Provedor: pague_dev, asaas, simulator pixCopyPastestring | null Código PIX copia e cola expiresAtstring | null Data de expiração (ISO 8601) confirmedAtstring | null Data de confirmação (ISO 8601) isTestboolean Se é pagamento de teste metadataobject | null Metadados customizados createdAtstring Data de criação (ISO 8601) updatedAtstring Data de atualização (ISO 8601)
Boas Práticas
Retorne um status 200 OK o mais rápido possível. Processe o evento de forma assíncrona se necessário.
Use o campo id do evento para evitar processar o mesmo evento mais de uma vez. Webhooks podem ser reenviados em caso de falha.
Configure sua URL de webhook com HTTPS para garantir a segurança dos dados transmitidos.
Retentativas Se sua URL de webhook retornar um erro (status >= 400), o Paybridge tentará reenviar o evento:
5 tentativas com backoff exponencialIntervalos: 2s → 4s → 8s → 16s → 32s
Após 5 tentativas falhas, o evento vai para uma fila de falhas
Você pode consultar o histórico de entregas e retentar manualmente pelo dashboard.
Testando Webhooks No modo de teste (pk_test_*), você pode usar ferramentas como webhook.site ou ngrok para receber webhooks em desenvolvimento local.
# Exemplo com ngrok ngrok http 3000 # Configure a URL no dashboard # https://abc123.ngrok.io/webhooks/paybridge
Webhooks de teste (isTest: true) são enviados apenas para webhooks configurados como teste no dashboard.
