Overview
Our webhook system delivers event notifications in real-time. When a subscribed event occurs (e.g., a payment’s status changes or an invoice’s status updates), our service will send a POST request to your configured endpoint.
Authentication
We pass the authentication token via an HTTP header named X-Webhook-Token. Your endpoint must verify this header’s value against the one you have on file with us. Only process the request if they match.
Example of a webhook request with authentication:
POST /your-endpoint HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-Webhook-Token: your_secret_token
{
"id": "some-uuid",
"event": "payment.status-updated",
"payload": {
// ...
}
}
Events
Below are the currently supported events:
| Event Type | Description |
|---|
payment.status-updated | Triggered whenever a payment’s status changes. |
invoice.status-updated | Triggered whenever an invoice’s status changes. |
How Webhooks Are Sent
When an event occurs, the webhook request body is structured as follows:
{
"id": "<UUID>",
"event": "<EventType>",
"payload": {
// event-specific data
}
}
-
id: A unique identifier (UUID) for the webhook event.
-
event: The event type, such as payment.status-updated or invoice.status-updated.
-
payload: An object containing the event-specific data (described below).
The X-Webhook-Token header is included separately from the JSON payload.
Webhook Payloads
Payment Status Updated (payment.status-updated)
This event is triggered when a payment’s status changes. The payload includes details about the updated payment, related invoice, and payment status history.
Payload Structure:
{
"payment": {
"id": "<string>",
"status": "<PaymentStatus>",
"amount": <number>,
"paymentMethod": "<PaymentMethod>",
"processedAt": "<string or null>",
"createdAt": "<string>",
"dueDate": "<YYYY-MM-DD>"
},
"paymentStatusHistory": [
{
"id": "<string>",
"previousStatus": "<PaymentStatus or null>",
"newStatus": "<PaymentStatus>"
}
],
"invoice": {
"id": "<string>",
"status": "<BillingCycleStatus>",
"startDate": "<string>",
"endDate": "<string>",
"totalAmount": <number>,
"isLocked": <boolean>,
"externalProcessorSyncStatus": "<ExternalProcessorSyncBillingCycleStatus>",
"closedReason": "<BillingCycleClosedReason or null>",
"customer": {
"id": "<string>",
"name": "<string>",
"externalId": "<string>"
},
"paymentAccount": {
"id": "<string>",
"businessName": "<string>",
"tradeName": "<string or null>",
"taxId": "<string or null>",
"email": "<string or null>",
"address": {
"id": "<string>",
"number": "<string>",
"zipCode": "<string>",
"street": "<string>",
"neighborhood": "<string>",
"city": "<string>",
"state": "<State>",
"country": "<Country>",
"complement": "<string or null>"
}
}
}
}
Invoice Status Updated (invoice.status-updated)
This event is triggered when an invoice’s status changes. The payload provides details of the invoice and any associated data.
Payload Structure:
{
"invoice": {
"id": "<string>",
"status": "<BillingCycleStatus>",
"startDate": "<string>",
"endDate": "<string>",
"totalAmount": <number>,
"isLocked": <boolean>,
"externalProcessorSyncStatus": "<ExternalProcessorSyncBillingCycleStatus>",
"closedReason": "<BillingCycleClosedReason or null>",
"customer": {
"id": "<string>",
"name": "<string>",
"externalId": "<string>"
},
"paymentAccount": {
"id": "<string>",
"businessName": "<string>",
"tradeName": "<string or null>",
"taxId": "<string or null>",
"email": "<string or null>",
"address": {
"id": "<string>",
"number": "<string>",
"zipCode": "<string>",
"street": "<string>",
"neighborhood": "<string>",
"city": "<string>",
"state": "<State>",
"country": "<Country>",
"complement": "<string or null>"
}
}
}
}
Enumerations
-
PaymentStatus: created, pending, paid, failed, canceled, expired
-
PaymentMethod: bolepix
-
BillingCycleStatus: open, closed, paid, canceled
-
BillingCycleClosedReason: end_of_cycle, billing_end_day_updated
-
ExternalProcessorSyncBillingCycleStatus: not_applicable, not_initiated, pending, success, failed
-
State: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO
-
Country: Brasil
Verifying Webhooks
-
Check the X-Webhook-Token Header: Ensure it matches the token you have registered.
-
Parse the JSON Payload: Review the event and payload.
-
Process the Event: Update your systems accordingly.
-
Respond with a 2XX Status: Acknowledge receipt to prevent retries.
Example
payment.status-updated Example Request:
POST /webhooks HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-Webhook-Token: secret_token_123
{
"id": "8a787b30-4d4d-4b2e-9e2f-a4d59214ecf0",
"event": "payment.status-updated",
"payload": {
"payment": {
"id": "pay_123",
"status": "paid",
"amount": 50000,
"paymentMethod": "bolepix",
"processedAt": "2024-12-13T10:20:30Z",
"createdAt": "2024-12-01T08:00:00Z",
"dueDate": "2024-12-31"
},
"paymentStatusHistory": [
{
"id": "hist_456",
"previousStatus": "pending",
"newStatus": "paid"
}
],
"invoice": {
"id": "inv_789",
"status": "paid",
"startDate": "2024-12-01",
"endDate": "2024-12-31",
"totalAmount": 50000,
"isLocked": false,
"externalProcessorSyncStatus": "success",
"closedReason": null,
"customer": {
"id": "cust_abc",
"name": "John Doe",
"externalId": "ext_123"
},
"paymentAccount": {
"id": "acc_xyz",
"businessName": "Doe Enterprise",
"tradeName": null,
"taxId": null,
"email": "billing@doe-enterprise.com",
"address": {
"id": "addr_001",
"number": "123",
"zipCode": "12345-678",
"street": "Main St",
"neighborhood": "Downtown",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"complement": null
}
}
}
}
}
