> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybridge.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Receba notificações em tempo real sobre eventos de pagamento
## 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:
```json theme={null}
{
"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
Enviado imediatamente após a criação de um pagamento.
```json theme={null}
{
"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"
}
}
}
```
Enviado quando um pagamento PIX é confirmado.
```json theme={null}
{
"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"
}
}
}
```
Enviado quando um pagamento expira sem ser pago.
```json theme={null}
{
"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"
}
}
}
```
Enviado quando um pagamento é cancelado.
```json theme={null}
{
"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"
}
}
}
```
Enviado quando um pagamento é reembolsado.
```json theme={null}
{
"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"
}
}
}
```
Enviado quando ocorre uma falha ao criar o pagamento no provedor. Este evento tem uma estrutura diferente dos demais.
```json theme={null}
{
"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
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 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](https://webhook.site) ou [ngrok](https://ngrok.com) para receber webhooks em desenvolvimento local.
```bash theme={null}
# 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.