Webhooks are not available by default. Please contact your sales representative to activate webhooks for your shop integration.

To send updates on relevant events, Billie sends POST requests to the incoming webhook endpoint provided by the merchant.
See "Event Names" section for the list of events that can be communicated via webhooks.

Webhook Authentication

The authentication for webhooks sent from Billie to the merchants incoming webhook URL depends on the merchant specifications
and needs, but one possibility is sending the Billie API Key via headers:

  • Authorization: Basic THE_API_KEY
  • X-Api-Key: THE_API_KEY
  • X-Another-Custom-Header: THE_API_KEY

The merchants will need to verify on their server side the authentication mechanism and credentials.

Webhook Requests

A POST request is sent to the configured merchant Webhook URL with one of the API Key headers mentioned above,
the application/json Content-Type and the following body format:

    created_at: (datetime)
    event: (string) (event name, -check the following section for more details-)
    order_id: (string) (order external code)
    order_uuid: (string)
    invoice_uuid: (string) (optional)
    amount: (string) (optional) (contains sum of paid amounts)
    open_amount: (string) (optional) (contains sum of outstanding amount)


	"event": "order_approved",
	"order_id": "1234567890",
	"created_at": "2023-07-24 14:19:32",
	"order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7"
	"event": "invoice_paid_out",
	"order_id": "1234567890",
	"created_at": "2023-07-24 14:19:32",
	"order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7",
	"invoice_uuid": "03f74b37-3a04-4f76-aa88-221d01520e08",

Event Names

Order State Transitions

Event NameDescription
order_waitingOrder is not approved waiting for manual confirmation.
order_shippedOrder is shipped.
order_canceledWhen the order is canceled.

Invoice State Transitions

Event NameDescription
invoice_createdWhen the invoice is created
invoice_paid_outWhen the invoice is paid out
invoice_lateWhen the invoice payback is late
invoice_canceledWhen the invoice is canceled

Waiting State

Event NameDescription
order_approvedAn order that was in waiting state and after manual check has been approved.
order_declinedAn order that was in waiting state and after manual check has been declined.

Webhooks for Dunning & Collections

From our dunning provider (Receeve) this events will be available:

Event NameDescription
dunningDunning process has been started
promise_to_payDebtor stated a promise to pay
instalment_planDebtor asked for instalment plan
disputeDebtor disputed claim
dunning_pausedDunning process has been paused
archivedArchived cases, mostly unsuccessful
closedClosed, because of merchant or debtor payment
dcaCase has been handed over to a collection agency


Event NameDescription
paymentWhen an Invoice is paid back partially or fully a message will be sent.
clawbackThe debtor clawedback the direct debit payment. Please refer to the GET invoice endpoint to check the new invoice outstanding amount and state