> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincle.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Asynchronous notification of events to the integrator's system.

Webhooks are the mechanism by which the platform communicates, asynchronously, the events relating to transactions, infractions and transfers. For each event, the platform sends an HTTP `POST` request to the URL designated by the integrator.

## Endpoint types

There are two types of endpoint, which may be used together.

| Type | Configuration | Coverage |
| - | - | - |
| Per transaction | `postbackUrl` field, sent when creating the charge. | Events of the corresponding transaction. The notification body contains `scope: "postback"`. |
| Per account | Registration through `POST /webhooks`, with the list of subscribed events. | Selected events of all transactions of the account. The notification body contains `scope: "user"`. |

## Registration

The `POST /webhooks` operation registers the endpoint. The URL is verified at registration, and the absence of a response results in rejection of the request with status `400`. The endpoint must therefore be published beforehand.

```bash theme={null}
curl -X POST https://api.fincle.com.br/webhooks \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Financial management system",
    "url": "https://api.example.com/webhooks/fincle",
    "events": ["transaction_paid", "transaction_refunded", "infraction"]
  }'
```

## Events

| Event | Occurrence |
| - | - |
| `transaction_created` | Creation of a transaction. |
| `transaction_paid` | Confirmation of a payment. |
| `transaction_updated` | Change in the status of a transaction. |
| `card_declined` | Decline of a card charge. |
| `refund_requested` | Refund request submitted by the payer. |
| `transaction_refunded` | Return of a payment. |
| `infraction` | Opening or update of an infraction. |
| `transfer_created` | Creation of a transfer. |
| `transfer_updated` | Change in the status of a transfer. |
| `transfer_completed` | Completion of a transfer. |
| `transfer_canceled` | Cancellation of a transfer. |

## Notification structure

The notification body is a JSON object. The top-level fields are common to all events.

| Field | Description |
| - | - |
| `id` | Unique identifier of the notification. |
| `type` | Source of the event: `transaction`, `transfer` or `infraction`. |
| `event` | Event that occurred. |
| `scope` | Endpoint type: `user` or `postback`. |

### Transaction event

```json theme={null}
{
  "id": "0d6e13bf-d348-4282-aebd-769f142ebcee",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "user",
  "transaction": {
    "id": "cmddiqpxo09zf1yju2kqkhgga",
    "amount": 125000,
    "netAmount": 123750,
    "status": "paid",
    "pix": {
      "endToEndId": "E18236120202611121410s12e9976c00",
      "payerInfo": null
    },
    "paidAt": "2026-11-12T14:10:17.000Z"
  },
  "customer": {
    "name": "Helena Martins Andrade",
    "email": "helena.andrade@example.com",
    "phone": "11932104567",
    "document": "31845792041",
    "documentType": "cpf",
    "purchaseDate": "2026-11-12T14:08:06.000Z"
  }
}
```

| Field | Description |
| - | - |
| `transaction.id` | Transaction identifier. |
| `transaction.amount` | Gross amount, in cents. |
| `transaction.netAmount` | Net amount, after fees, in cents. |
| `transaction.status` | Status of the transaction at the time of the event. |
| `transaction.pix` | Pix data, when applicable: end-to-end identifier and payer information reported by the institution. |
| `transaction.paidAt` | Time at which the payment was confirmed. |
| `customer` | Identification of the payer. |

For declined card charges, the `transaction` block additionally contains the `refuseReason`, `acquirerCode` and `acquirerMessage` fields.

### Transfer event

```json theme={null}
{
  "id": "5b8e2c41-7d93-4f06-b2a8-1e6c9d3f7a52",
  "type": "transfer",
  "event": "transfer_completed",
  "scope": "user",
  "transfer": {
    "id": "cmdeqa3g300051wjn7gtacf1t",
    "amount": 1500000,
    "status": "completed",
    "pix": {
      "endToEndId": "E35713491202611121607s29656e25f1",
      "creditorAccount": null
    }
  }
}
```

The structure of the infraction event is set out in [Infractions and MED](https://docs.fincle.com.br/guides/infractions-and-med.md).

## Acknowledgement

The endpoint must respond with a `2xx` status to acknowledge receipt. Any other response, as well as the absence of a response, is recorded as a delivery failure. It is recommended that the endpoint acknowledge receipt immediately and perform processing asynchronously.

## Retries

In the event of failure, the platform repeats the delivery, up to a limit of five attempts per notification. Once the limit is exhausted, the delivery remains recorded as failed and may be resent at the integrator's request.

## Endpoint requirements

Notification delivery follows at-least-once semantics. The endpoint must therefore meet the following requirements:

* process each notification idempotently, using the `id` field to identify repetitions
* not assume the order of arrival of notifications, and base decisions on the status reported in `transaction.status`
* confirm the status of the transaction through `GET /transactions/{transactionId}` before any irreversible act, as set out in [Security and data protection](https://docs.fincle.com.br/guides/security.md)

## Testing

The `POST /webhooks/{webhookId}/test` operation sends test notifications, with fictitious data, to the registered URL and returns the HTTP status returned by the endpoint for each delivery. No real transaction is created or changed.

## Audit and redelivery

The `GET /webhook-deliveries` operation lists the delivery attempts, with the event, the status and the destination URL. The `status=error` filter identifies the deliveries rejected by the endpoint. The `GET /webhook-deliveries/{deliveryId}` operation returns the body sent and the response received in each attempt, which makes it possible to determine the origin of the failure. Once the endpoint is corrected, the `POST /webhook-deliveries/{deliveryId}/retry` operation requests redelivery with the same body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.