> For the complete documentation index, see [llms.txt](https://docs.pagou.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-boleto/webhooks.md).
# Webhooks
## Webhooks para Interações com Boletos
Os webhooks da API do Pagou permitem receber notificações assíncronas sobre eventos relacionados a boletos, como a criação ou confirmação de pagamento. Esta seção detalha os eventos `charge.created` e `charge.paid`, suas estruturas de payload, configuração do `notification_url`, autenticação, validação, exemplos de código, tratamento de erros e boas práticas para processar webhooks de forma robusta e segura.
### Visão Geral Técnica
A API do Pagou envia notificações via requisições HTTP POST para o `notification_url` configurado ao criar um boleto (via `POST` `/v1/charges`). Os eventos disponíveis para boletos são:
* `charge.created`: Notifica quando um boleto é criado com sucesso, fornecendo detalhes como código de barras e linha digitável.
* `charge.paid`: Notifica quando um boleto é pago, indicando que o pagamento foi confirmado.
Os webhooks são enviados em formato JSON e requerem um endpoint HTTPS público no lado do cliente para processamento. A API realiza até 10 tentativas de entrega do webhook, com intervalos exponenciais, até receber uma resposta 200 OK. Se o endpoint não responder com 200 OK, a API reenvia o webhook, exigindo que o processamento seja idempotente.
**Especificações**:
* **Método**: `POST`
* **Content-Type**: `application/json`
* **URL**: Configurada no campo `notification_url` ao criar o boleto.
* **Evento**: `charge.paid`.
* **Reenvios**: Até **10 tentativas** até receber `200 OK`.
### Configuração do Webhook
1. **Definir o** `notification_url`: Ao criar um boleto via `POST`` ``/v1/charges`, inclua o campo `notification_url` (ex.: ) no corpo da requisição (veja [Criando um Boleto](/integracao-com-a-api/meio-de-pagamento-boleto/criando-um-boleto.md)).
2. **Implementar o endpoint**: Crie um endpoint HTTP `POST` no seu servidor para receber e processar os payloads JSON.
3. **Garantir HTTPS**: Use um certificado SSL válido para o `notification_url`.
### Estrutura do Webhook
#### Evento: charge.created
Notifica quando um boleto é criado com sucesso, fornecendo detalhes como código de barras e linha digitável.
**Payload**:
```json
{
"name": "charge.created",
"data": {
"id": "6bd30949-248e-44c8-8b20-cca8bf6f2686",
"transactionid": "22bf12b8-77fa-429f-b216-2accf48600eb",
"clientcode": "6bd30949-248e-44c8-8b20-cca8bf6f2686",
"payload": {
"transaction_id": "32bf21d3-55fa-429f-b216-2accf48600ac",
"bank_emissor": "CELCOIN INSTITUIÇÃO DE PAGAMENTO - SA",
"bank_number": "1701112",
"bank_agency": "0001",
"bank_account": "999911111",
"bar_code": "99990000000000099990000000000000000000000000",
"line": "99990000000000000000000000000000000080000009999",
"bank_assignor": "CELCOIN INSTITUIÇÃO DE PAGAMENTO - SA"
}
}
}
```
**Campos do Payload**:
| Campo | Tipo | Descrição |
| ---------------------------- | ------ | --------------------------------------------------- |
| name | string | Nome do evento (charge.created). |
| data | object | Dados do evento. |
| data.id | string | ID do boleto. |
| data.transactionid | string | ID da transaçã. |
| data.clientcode | string | Identificador do ID do boleto. |
| data.payload | object | Detalhes do boleto. |
| data.payload.transaction\_id | string | ID da transação, redundante com data.transactionid. |
| data.payload.bank\_emissor | string | Nome da instituição emissora |
| data.payload.bank\_number | string | Código do banco |
| data.payload.bank\_agency | string | Agência bancária |
| data.payload.bank\_account | string | Conta bancária. |
| data.payload.bar\_code | string | Código de barras do boleto. |
| data.payload.line | string | Linha digitável do boleto. |
| data.payload.bank\_assignor | string | Nome do cedente. |
#### Evento: charge.paid
Notifica quando um boleto é pago, indicando que o pagamento foi confirmado.
**Payload**:
```json
{
"name": "charge.paid",
"data": {
"id": "09cd8523-85e8-400f-9c06-3c1950714d6b",
"transactionid": "a21b0b0f-e142-49e8-a81f-1095527f2ef2",
"clientcode": "09cd8523-85e8-400f-9c06-3c1950714d6b",
"amount": {
"paid": 94.99,
"original": 94.99
},
"paidin": "2025-07-23 08:00:06"
}
}
```
**Campos do Payload**:
| Campo | Tipo | Descrição |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| name | string | Nome do evento (charge.paid). |
| data | object | Dados do evento. |
| data.id | string | UUID do boleto (ex.: 09cd8523-85e8-400f-9c06-3c1950714d6b). |
| data.transactionid | string | ID da transação de pagamento (ex.: a21b0b0f-e142-49e8-a81f-1095527f2ef2). |
| data.clientcode | string | Identificador do cliente (ex.: 09cd8523-85e8-400f-9c06-3c1950714d6b, equivalente a customer\_id). |
| data.amount | object | Detalhes do valor do boleto. |
| data.amount.paid | number | Valor pago em reais (ex.: 94.99). |
| data.amount.original | number | Valor original do boleto em reais (ex.: 94.99). |
| data.paidin | string | Data e hora do pagamento (formato YYYY-MM-DD HH:MM:SS, ex.: 2025-07-23 08:00:06). |
| data.paymenttype | string | Tipo de pagamento (ex.: vazio no exemplo, pode ser bank\_slip ou similar). |
**Resposta Esperada**:
* Retorne `200 OK` para confirmar o recebimento e evitar reenvios (até **10 tentativas** pela API).
* Outros códigos (ex.: 400, 401) acionam reenvios pela API do Pagou.