💡

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 PAD sends POST requests to the incoming webhook URL 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:

Examples:
- 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)
      amount: (string) (optional) (contains sum of paid amounts)
      open_amount: (string) (optional) (contains sum of outstanding amount)
  }


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_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

Depending on the dunning provider, one of the two sets of the events will be available:


Events for CollectAi provider

Event NameDescription
reminder_email_11st Reminder mail was sent
reminder_email_22nd Reminder mail was sent
dunning_letter_11st Dunning letter was sent
dunning_email_11st Dunning mail was sent
reminder_email_33rd Reminder email was sent
dunning_letter_22nd Dunning letter was sent
dunning_email_22nd Dunning email was sent
reminder_email_44th Reminder email was sent
dca_emailHandover to collections email was sent

Events for Receeve provider

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


Payments

Event NameDescription
paymentWhen an Invoice is paid back partially or fully a message will be sent.