Skip to main content

​
Overview

Our webhook system delivers event notifications in real-time. When a subscribed event occurs (e.g., 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": "invoice.status-updated",
  "payload": {
    // ...
  }
}

​
Events

Below are the currently supported events:
Event TypeDescription
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 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

​
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>",
    "customer": {
      "id": "<string>",
      "name": "<string>",
      "externalId": "<string>"
    },
    "billingAccount": {
      "businessName": "<string>",
      "taxId": "<string>",
      "taxIdType": "<TaxIdType>"
    },
    "invoiceNumber": "<string>",
    "invoiceDate": "<string>",
    "dueDate": "<string or null>",
    "totalAmount": <number>,
    "status": "<InvoiceStatus>"
  },
  "changes": {
    "oldStatus": "<InvoiceStatus>",
    "newStatus": "<InvoiceStatus>"
  }
}

​
Enumerations

  • InvoiceStatus: open, in_review, issued, synced, pending, paid, overdue, canceled, failed

​
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.