Webhook Documentation
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:
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
: A unique identifier (UUID) for the webhook event. -
event
: The event type, such aspayment.status-updated
orinvoice.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:
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:
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
andpayload
. -
Process the Event: Update your systems accordingly.
-
Respond with a 2XX Status: Acknowledge receipt to prevent retries.
Example
payment.status-updated
Example Request: