Naar de hoofdinhoud

Facturatiewebhooks instellen en gebruiken

Met facturatiewebhooks kun je automatisch factuurgegevens vanuit bsport naar een ander systeem sturen (zoals je boekhoudsoftware of interne

Wat is een webhook?

Een webhook is een automatisch bericht dat vanuit ons systeem naar een andere applicatie wordt gestuurd zodra er iets belangrijks gebeurt, bijvoorbeeld wanneer een factuur wordt aangemaakt of teruggedraaid. Je ontvangt deze meldingen direct, zodat je in realtime kunt reageren.

Hiermee kun je:

  • Facturen synchroniseren met boekhoudtools

  • Automatiseringen activeren

  • Externe systemen in realtime up-to-date houden

Let op: voor webhooks is technische configuratie nodig; het zijn geen plug-and-play functies. Zorg dat je kennis hebt van softwareontwikkeling voordat je deze handleiding volledig doorloopt.

Voordat je begint

Om facturatiewebhooks te gebruiken, heb je een beveiligd HTTPS-eindpunt (URL) nodig dat POST-verzoeken met JSON-gegevens kan ontvangen.

Stapsgewijze handleiding

  1. Zodra je eindpunt klaar is, ga je naar https://backoffice.bsport.io/settings/webhook.

  2. Klik op de knop 'Webhook toevoegen'

  3. Selecteer de gebeurtenis waarop je je wilt abonneren (typen gebeurtenissen vind je hier).

  4. Voer de URL in waar de webhook het bericht naartoe moet sturen.

  5. Klik op bevestigen.

  6. Je nieuwe webhook is nu aangemaakt 🎉.

  7. (Optioneel) Door op de knop 'Test' te klikken, kun je een gebeurtenis simuleren om te controleren of je webhook werkt.

Typen gebeurtenissen

Je kunt je abonneren op verschillende gebeurtenissen die te maken hebben met de levenscyclus van een factuur:

  • invoice-finalize – wordt geactiveerd wanneer een factuur wordt aangemaakt en geopend (afgerond).

  • invoice-revert – wordt geactiveerd wanneer een factuur wordt teruggedraaid (geannuleerd of terugbetaald)

  • invoice-pay – wordt geactiveerd wanneer een factuur volledig is betaald.

  • invoice-dispute – wordt geactiveerd wanneer een factuur wordt betwist.

De volgende factuurgebeurtenissen zijn verouderd en mogen daarom niet meer worden gebruikt.

  • invoice-create

  • invoice-update

Gebeurtenis-payload

Elk van deze gebeurtenissen verzendt dezelfde payload-structuur, zoals hieronder gedefinieerd.

Je vindt hier ook de JSON Schema-beschrijving van de payload.

Beschrijving van de velden

Veld

Type

Beschrijving

Voorbeeld

event_type

string

Type gebeurtenis

"invoice-finalize"

date

number (timestamp)

Tijdstempel van wanneer de gebeurtenis werd geactiveerd

1762246989

data

Object

Details over de gebeurtenis en factuur (zie hieronder).

-

data.date

"2025-11-04T09:03:11.653072Z"

data.object.id

string (uuid)

Unieke identificatie van de factuur

"923e2c97-8228-4d42-8a44-1783c70c50a1"

data.object.object

string

Objecttype (altijd invoice).

"invoice"

data.object.status

string

Factuurstatus (open, paid, refunded, voided).

"open"

data.object.date_created

string (date-time)

Wanneer de factuur is aangemaakt (UTC).

"2025-11-04T09:03:06.515219Z"

data.object.date_created

string (date-time)

Wanneer de factuur is aangemaakt (UTC).

"2025-11-04T09:03:06.515219Z"

data.object.date_issued

string (date-time)

Wanneer de factuur is uitgegeven (UTC).

"2025-11-04T09:03:08.225042Z"

data.object.date_due

string (date-time)

Vervaldatum van betaling (UTC).

"2025-11-04T09:03:07.292000Z"

data.object.date_cancelled

string (date-time) | null

Wanneer de factuur is geannuleerd (indien van toepassing).

null

data.object.currency

string

Valuta van de factuur (ISO 4217-code).

"eur"

data.object.total

number (cents)

Totaalbedrag van de factuur in de kleinste eenheid (bijv. centen).

36665

data.object.amount_due

number (cents)

Verschuldigd bedrag in de kleinste eenheid (bijv. centen).

36665

data.object.amount_paid

number (cents)

Reeds betaald bedrag in de kleinste eenheid (bijv. centen).

0

data.object.company

object

Bedrijf dat de factuur uitgeeft.

{ ... }

data.object.company.id

number

Unieke bedrijfs-ID. Ga naar deze backoffice-pagina om je bedrijfs-ID te vinden.

85329

data.object.company.name

string

Bedrijfsnaam.

"SaudeViva Portugal"

data.object.company.country

string

Landcode.

"PT"

data.object.company.city

string

Plaats.

"Lisbon"

data.object.company.address

string

Adres.

"Rua do Ouro 115"

data.object.company.postal_code

string

Postcode.

"1100-062"

data.object.customer

object | null

Klant aan wie wordt gefactureerd (kan null zijn voor anonieme kassa-facturen).

{ ... }

data.object.customer.id

number

Unieke klant-/lid-ID.

7644312

data.object.customer.type

string

Klanttype (hier altijd individual).

"individual"

data.object.customer.name

string

Volledige naam.

"Maria Oliveira"

data.object.customer.first_name

string

Voornaam.

"Maria"

data.object.customer.last_name

string

Achternaam.

"Oliveira"

data.object.customer.email

string

Email van de contactpersoon.

"maria.oliveira77@example.com"

data.object.customer.phone

string

Telefoonnummer.

"+351 912 345 678"

data.object.customer.official_document_id

string

Officieel/nationaal identificatienummer (kan fiscaal nummer/NIF zijn).

"PT-19847765"

data.object.customer.address

object

Adres van de klant.

{ ... }

data.object.customer.address.line1

string

Straatadres.

"Avenida da Liberdade 202"

data.object.customer.address.line2

string (optional)

Aanvullende adresgegevens.

"4º Esq."

data.object.customer.address.city

string

Plaats.

"Lisbon"

data.object.customer.address.postal_code

string

Postcode.

"1250-147"

data.object.customer.address.state

string

Staat/regio.

"Lisboa"

data.object.customer.address.country

string

Landcode.

"PT"

data.object.line_items

object

Container voor factuurregels.

{ ... }

data.object.line_items.line_count

number

Aantal factuurregels.

6

data.object.line_items.data

array<object>

Array van factuurregels.

[{ ... }, { ... }]

data.object.line_items.data[].id

number

Unieke identificatie van de factuurregel.

2153

data.object.line_items.data[].description

string

Naam/label van het product of de dienst.

"£100 General Gift Voucher"

data.object.line_items.data[].quantity

number

Aantal gekochte eenheden.

1

data.object.line_items.data[].tax_included_unit_amount

number (cents)

Eenheidsprijs incl. btw, in centen.

10000

data.object.line_items.data[].tax_included_amount

number (cents)

Totaalprijs incl. btw vóór korting (quantity * unit_amount).

10000

data.object.line_items.data[].voucher_applied

number (cents)

Korting/voucher toegepast op deze regel, in centen.

0

data.object.line_items.data[].line_total

number (cents)

Definitief regelbedrag na korting, in centen.

10000

data.object.line_items.data[].tax_breakdown

object

Details van de btw-berekening.

{ ... }

data.object.line_items.data[].tax_breakdown.rate

number (%)

Btw-tarief in procenten (bijv. 20 = 20%).

0

data.object.line_items.data[].tax_breakdown.total_tax

number (cents)

Totale btw inbegrepen in deze regel, in centen.

0

data.object.line_items.data[].tax_breakdown.unit_tax

number (cents)

Btw per eenheid, in centen.

0

data.object.line_items.data[].item_type

string

Type bsport-item (shop-product, pass, private_pass, consumer_giftcard, refund).

"consumer_giftcard"

data.object.invoice_pdf

string (url)

Link naar de factuur-PDF.

"https://assets.staging.bsport.io/.../invoice-24092226.pdf"

data.object.receipt_pdf

string (url) | null

Link naar de PDF van het betaalbewijs (indien van toepassing).

null

data.object.invoice_type

number

Factuurtype: 0=normaal, 1=omgekeerd, 2=creditnota, 3=migratie.

0

data.object.source_invoice_id

string (uuid) | null

UUID van de oorspronkelijke factuur die via deze factuur is geannuleerd (indien van toepassing).

null

Voorbeeld

{
  "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": "SaudeViva Portugal",
        "country": "PT",
        "city": "Lisbon",
        "address": "Rua do Ouro 115",
        "postal_code": "1100-062"
      },
      "customer": {
        "id": 7644312,
        "type": "individual",
        "name": "Maria Oliveira",
        "first_name": "Maria",
        "last_name": "Oliveira",
        "email": "maria.oliveira77@example.com",
        "phone": "+351 912 345 678",
        "official_document_id": "PT-19847765",
        "address": {
          "line1": "Avenida da Liberdade 202",
          "line2": "4º Esq.",
          "city": "Lisbon",
          "postal_code": "1250-147",
          "state": "Lisboa",
          "country": "PT"
        }
      },
      "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"
          },
          {
            "id": 249955,
            "description": "Classic Jumper - Peacoat Navy",
            "quantity": 2,
            "tax_included_unit_amount": 4500,
            "tax_included_amount": 9000,
            "voucher_applied": 964,
            "line_total": 8036,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 1339,
              "unit_tax": 670
            },
            "item_type": "shop-product"
          },
          {
            "id": 15305,
            "description": "Single 60 Minute Reiki Treatment",
            "quantity": 1,
            "tax_included_unit_amount": 7500,
            "tax_included_amount": 7500,
            "voucher_applied": 1384,
            "line_total": 6116,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 1019,
              "unit_tax": 1019
            },
            "item_type": "private_pass"
          },
          {
            "id": 15301,
            "description": "Single 60 Minute Session",
            "quantity": 1,
            "tax_included_unit_amount": 7500,
            "tax_included_amount": 7500,
            "voucher_applied": 1383,
            "line_total": 6117,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 1019,
              "unit_tax": 1019
            },
            "item_type": "private_pass"
          },
          {
            "id": 427448,
            "description": "Newbies",
            "quantity": 1,
            "tax_included_unit_amount": 4900,
            "tax_included_amount": 4900,
            "voucher_applied": 904,
            "line_total": 3996,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 666,
              "unit_tax": 666
            },
            "item_type": "pass"
          },
          {
            "id": 427451,
            "description": "1 Session",
            "quantity": 1,
            "tax_included_unit_amount": 2500,
            "tax_included_amount": 2500,
            "voucher_applied": 100,
            "line_total": 2400,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 400,
              "unit_tax": 400
            },
            "item_type": "pass"
          }
        ]
      },
      "invoice_pdf": "https://assets.staging.bsport.io/invoices/2025-11-04/5cab7c93-cd01-4d15-9362-46b0a89919b5/invoice-24092226.pdf",
      "receipt_pdf": null,
      "invoice_type": 0,
      "source_invoice_id": null
    }
  }
}
Was dit een antwoord op uw vraag?