​
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 TypeDescription
payment.status-updatedTriggered whenever a payment’s status changes.
invoice.status-updatedTriggered 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

  1. Check the X-Webhook-Token Header: Ensure it matches the token you have registered.

  2. Parse the JSON Payload: Review the event and payload.

  3. Process the Event: Update your systems accordingly.

  4. 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
        }
      }
    }
  }
}