Webhooks - Paybridge

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.created`	Pagamento foi criado com sucesso
`payment.pending`	Pagamento está aguardando confirmação
`payment.confirmed`	Pagamento foi confirmado
`payment.expired`	Pagamento expirou sem ser pago
`payment.cancelled`	Pagamento foi cancelado
`payment.refunded`	Pagamento foi reembolsado
`payment.failed`	Falha 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
`id`	string	Identificador único do evento
`type`	string	Tipo do evento (ex: `payment.confirmed`)
`created`	number	Timestamp Unix em segundos
`data`	object	Dados específicos do evento

Exemplos de Payload

payment.created

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": "joao@email.com",
      "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"
    }
  }
}

payment.confirmed

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": "joao@email.com",
      "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"
    }
  }
}

payment.expired

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": "maria@email.com",
      "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"
    }
  }
}

payment.cancelled

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": "carlos@email.com",
      "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"
    }
  }
}

payment.refunded

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": "ana@email.com",
      "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"
    }
  }
}

payment.failed

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": "pedro@email.com",
      "provider": "asaas",
      "isTest": false,
      "metadata": null
    },
    "error": {
      "message": "Invalid credentials provided",
      "provider": "asaas"
    }
  }
}

Estrutura do Objeto Payment

Campo	Tipo	Descrição
`id`	string	ID único do pagamento
`externalId`	string \| null	ID de referência externa
`amount`	number	Valor em BRL (ex: 10.50)
`currency`	string	Moeda (sempre “BRL”)
`description`	string \| null	Descrição do pagamento
`payerName`	string \| null	Nome do pagador
`payerDocument`	string \| null	CPF ou CNPJ do pagador
`payerEmail`	string \| null	E-mail do pagador
`status`	string	Status: `pending`, `confirmed`, `expired`, `cancelled`, `refunded`
`provider`	string	Provedor: `pague_dev`, `asaas`, `simulator`
`pixCopyPaste`	string \| null	Código PIX copia e cola
`expiresAt`	string \| null	Data de expiração (ISO 8601)
`confirmedAt`	string \| null	Data de confirmação (ISO 8601)
`isTest`	boolean	Se é pagamento de teste
`metadata`	object \| null	Metadados customizados
`createdAt`	string	Data de criação (ISO 8601)
`updatedAt`	string	Data de atualização (ISO 8601)

Boas Práticas

Responda rapidamente

Retorne um status 200 OK o mais rápido possível. Processe o evento de forma assíncrona se necessário.

Implemente idempotência

Use o campo id do evento para evitar processar o mesmo evento mais de uma vez. Webhooks podem ser reenviados em caso de falha.

Use HTTPS

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 exponencial
Intervalos: 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.

​Visão Geral

​Eventos Disponíveis

​Estrutura do Payload

​Exemplos de Payload

​Estrutura do Objeto Payment

​Boas Práticas

​Retentativas

​Testando Webhooks

Visão Geral

Eventos Disponíveis

Estrutura do Payload

Exemplos de Payload

Estrutura do Objeto Payment

Boas Práticas

Retentativas

Testando Webhooks