# 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-boleto/webhooks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.