Invoice webhook (Back Office legacy)¶

Back Office webhook (legacy)

This article applies only to the legacy registration configured in Settings > Webhook. New Public API registrations use /api/v2/management/webhook-registrations/ and follow the V2 payload reference. Existing V1 registrations keep their historical contract.

Overview¶

The Invoice webhook sends invoice lifecycle events so your external systems can react in near real time. Typical use cases include accounting sync, payment follow-up automation, and invoice audit workflows.

Who It Is For¶

Teams integrating bsport invoicing with accounting systems.
Operations and finance teams tracking invoice state transitions.
Support teams troubleshooting invoice and payment lifecycle events.

Supported Events¶

Current events:

invoice-finalize: triggered when an invoice is created and finalized.
invoice-revert: triggered when an invoice is reverted.
invoice-pay: triggered when an invoice becomes fully paid.
invoice-dispute: triggered when an invoice is disputed.

Deprecated events:

invoice-create
invoice-update

These event names remain documented only to support existing Back Office integrations.

Inspect an existing registration¶

Open https://backoffice.bsport.io/settings/webhook.
Locate the existing invoice registration.
Verify its event and destination before planning the migration.

New integrations use V2 invoice webhooks. The V2 events report invoice and line-item mutations; they do not preserve the Back Office lifecycle-event names or payload. Keep this reference when maintaining an existing Back Office registration.

Payload Envelope¶

All invoice events use the same envelope:

{
  "event_type": "invoice-finalize",
  "date": 1762246989,
  "data": {
    "date": "2025-11-04T09:03:11.653072Z",
    "object": {}
  }
}

The payload schema reference currently used in documentation is available here:

https://downloads.intercomcdn.com/i/o/q6foivp2/2103372445/891be3e80f0fe2ac84ab25d646ec/invoice-webhook-payload_schema.json

Data Fields¶

Field	Type	Description	Example
`event_type`	string	Invoice event type.	`"invoice-finalize"`
`date`	number	Unix timestamp when event was triggered.	`1762246989`
`data`	object	Event body.	`{ ... }`
`data.date`	string (date-time)	Event date-time in UTC.	`"2025-11-04T09:03:11.653072Z"`
`data.object.id`	string (uuid)	Invoice identifier.	`"923e2c97-8228-4d42-8a44-1783c70c50a1"`
`data.object.object`	string	Object type, expected `invoice`.	`"invoice"`
`data.object.status`	string	Invoice status (`open`, `paid`, `refunded`, `voided`).	`"open"`
`data.object.date_created`	string (date-time)	Invoice creation datetime in UTC.	`"2025-11-04T09:03:06.515219Z"`
`data.object.date_issued`	string (date-time)	Invoice issue datetime in UTC.	`"2025-11-04T09:03:08.225042Z"`
`data.object.date_due`	string (date-time)	Payment due datetime in UTC.	`"2025-11-04T09:03:07.292000Z"`
`data.object.date_cancelled`	string (date-time) or null	Cancellation datetime in UTC when applicable.	`null`
`data.object.currency`	string	Currency code (ISO 4217).	`"eur"`
`data.object.total`	number (minor unit)	Total amount in smallest currency unit.	`36665`
`data.object.amount_due`	number (minor unit)	Due amount in smallest currency unit.	`36665`
`data.object.amount_paid`	number (minor unit)	Paid amount in smallest currency unit.	`0`
`data.object.company`	object	Issuing company data.	`{ ... }`
`data.object.company.id`	number	Company id.	`85329`
`data.object.company.name`	string	Company name.	`"SaudeViva Portugal"`
`data.object.company.country`	string	Company country code.	`"PT"`
`data.object.company.city`	string	Company city.	`"Lisbon"`
`data.object.company.address`	string	Company address.	`"Rua do Ouro 115"`
`data.object.company.postal_code`	string	Company postal code.	`"1100-062"`
`data.object.customer`	object or null	Customer object. Can be `null` for anonymous POS invoices.	`{ ... }`
`data.object.customer.id`	number	Customer/member id.	`7644312`
`data.object.customer.type`	string	Customer type.	`"individual"`
`data.object.customer.name`	string	Customer full name.	`"Maria Oliveira"`
`data.object.customer.first_name`	string	Customer first name.	`"Maria"`
`data.object.customer.last_name`	string	Customer last name.	`"Oliveira"`
`data.object.customer.email`	string	Customer email.	`"maria.oliveira77@example.com"`
`data.object.customer.phone`	string	Customer phone number.	`"+351 912 345 678"`
`data.object.customer.official_document_id`	string	Official or national document id.	`"PT-19847765"`
`data.object.customer.address`	object	Customer address details.	`{ ... }`
`data.object.customer.address.line1`	string	Address line 1.	`"Avenida da Liberdade 202"`
`data.object.customer.address.line2`	string (optional)	Address line 2.	`"4o Esq."`
`data.object.customer.address.city`	string	Address city.	`"Lisbon"`
`data.object.customer.address.postal_code`	string	Address postal code.	`"1250-147"`
`data.object.customer.address.state`	string	Address region/state.	`"Lisboa"`
`data.object.customer.address.country`	string	Address country code.	`"PT"`
`data.object.line_items`	object	Line item container.	`{ ... }`
`data.object.line_items.line_count`	number	Number of invoice lines.	`6`
`data.object.line_items.data`	array	List of invoice lines.	`[{ ... }]`
`data.object.line_items.data[].id`	number	Line item id.	`2153`
`data.object.line_items.data[].description`	string	Line description.	`"100 General Gift Voucher"`
`data.object.line_items.data[].quantity`	number	Quantity.	`1`
`data.object.line_items.data[].tax_included_unit_amount`	number (minor unit)	Unit amount including tax.	`10000`
`data.object.line_items.data[].tax_included_amount`	number (minor unit)	Total amount including tax before discount.	`10000`
`data.object.line_items.data[].voucher_applied`	number (minor unit)	Discount applied.	`0`
`data.object.line_items.data[].line_total`	number (minor unit)	Final line amount after discount.	`10000`
`data.object.line_items.data[].tax_breakdown`	object	Tax details per line.	`{ ... }`
`data.object.line_items.data[].tax_breakdown.rate`	number	Tax rate percentage.	`20`
`data.object.line_items.data[].tax_breakdown.total_tax`	number (minor unit)	Total tax included in line amount.	`1339`
`data.object.line_items.data[].tax_breakdown.unit_tax`	number (minor unit)	Unit tax included per quantity.	`670`
`data.object.line_items.data[].item_type`	string	bsport item type (`shop-product`, `pass`, `private_pass`, `consumer_giftcard`, `refund`).	`"consumer_giftcard"`
`data.object.invoice_pdf`	string (url)	Invoice PDF URL.	`"https://assets.staging.bsport.io/.../invoice-24092226.pdf"`
`data.object.receipt_pdf`	string (url) or null	Receipt PDF URL when applicable.	`null`
`data.object.invoice_type`	number	Invoice type (`0` normal, `1` reverse, `2` credit note, `3` migration).	`0`
`data.object.source_invoice_id`	string (uuid) or null	Source invoice uuid when this invoice references another invoice.	`null`

Example Payload¶

{
  "event_type": "invoice-finalize",
  "date": 1762246989,
  "data": {
    "date": "2025-11-04T09:03:11.653072Z",
    "object": {
      "id": "923e2c97-8228-4d42-8a44-1783c70c50a1",
      "object": "invoice",
      "status": "open",
      "date_created": "2025-11-04T09:03:06.515219Z",
      "date_issued": "2025-11-04T09:03:08.225042Z",
      "date_due": "2025-11-04T09:03:07.292000Z",
      "date_cancelled": null,
      "currency": "eur",
      "total": 36665,
      "amount_due": 36665,
      "amount_paid": 0,
      "company": {
        "id": 85329,
        "name": "bsport",
        "country": "ES",
        "city": "Barcelona",
        "address": "Passatge de Tasso 8",
        "postal_code": ".."
      },
      "customer": {
        "id": 7644312,
        "type": "individual",
        "name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe88@example.com",
        "phone": "+...",
        "official_document_id": "...",
        "address": {
          "line1": "",
          "line2": "",
          "city": "",
          "postal_code": "",
          "state": "Barcelona",
          "country": "ES"
        }
      },
      "line_items": {
        "line_count": 6,
        "data": [
          {
            "id": 2153,
            "description": "100 General Gift Voucher",
            "quantity": 1,
            "tax_included_unit_amount": 10000,
            "tax_included_amount": 10000,
            "voucher_applied": 0,
            "line_total": 10000,
            "tax_breakdown": {
              "rate": 0,
              "total_tax": 0,
              "unit_tax": 0
            },
            "item_type": "consumer_giftcard"
          }
        ]
      },
      "invoice_pdf": "https://assets.bsport.io/invoices/2025-11-04/uuid/invoice-333.pdf",
      "receipt_pdf": null,
      "invoice_type": 0,
      "source_invoice_id": null
    }
  }
}

Delivery, Reliability, And Security¶

Your endpoint must accept POST over HTTPS.
A documented retry policy is not currently specified in this guide.
Event ordering guarantees are not currently documented.
Signature verification headers are not currently documented.

Implementation approach:

Make event handling idempotent by invoice id and event type.
Treat amounts as minor units (for example cents) in downstream processing.
Persist full payloads for accounting traceability.

Troubleshooting¶

Missing invoice events: verify the webhook is configured for the exact invoice event type.
Amount mismatch in downstream systems: confirm minor-unit conversion logic.
Customer data can be null: handle anonymous POS invoice cases.

FAQ¶

Should a new integration use these invoice events?¶

No. All events on this page belong to the retiring Back Office webhook system. New integrations use V2 invoice webhooks: invoice.created and invoice.updated report invoice and line-item mutations, not the lifecycle transitions documented on this legacy page.