Webhooks

📘
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:
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 endpoint 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 Names

Order State Transitions

Event Name	Description
order_waiting	Order is not approved waiting for manual confirmation.
order_created	Order is created.
order_shipped	Order is shipped.
order_canceled	When the order is canceled.
order_paid_out	When the order is paid out.

Examples

{
  "event": "order_waiting",
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7"
}

{
  "event": "order_created",
  "external_code": "order-external-code",
  "amount": {
    "net": "80.00",
    "tax": "20.00",
    "gross": "100.00"
  },
  "debtor": {
    "name": "Zeta Electronics Gold GmbH",
    "billing_address": {
      "city": "Haslach im Kinzigtal",
      "street": "Tannenweg",
      "country": "DE",
      "postal_code": "77716",
      "house_number": "4"
    },
    "company_address": {
      "city": "Haslach im Kinzigtal",
      "street": "Tannenweg",
      "country": "DE",
      "postal_code": "77716",
      "house_number": "4"
    }
  },
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7",
  "references": [],
  "session_id": "790a101a-369a-4272-bea4-5c405ce6a8fa",
  "external_code": "1234567890",
  "payment_details": {
    "bic": "FRSDDEF1",
    "iban": "DE00000000000123456789",
    "bank_account_owner": "your-account-name"
  },
  "delivery_address": {
    "city": "Berlin",
    "street": "Charlottenstraße",
    "country": "DE",
    "postal_code": "10969",
    "house_number": "4"
  }
}

{
  "event": "order_shipped",
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7"
}

{
  "event": "order_canceled",
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7"
}

{
  "event": "order_paid_out",
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7"
}

Invoice State Transitions

Event Name	Description
invoice_created	When the invoice is created
invoice_paid_out	When the invoice is paid out
invoice_late	When the invoice payback is late

Examples

{
  "event": "invoice_created",
  "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": "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": "invoice_late",
  "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",
}

Waiting State

Event Name	Description
order_approved	An order that was in waiting state and after manual check has been approved.
order_declined	An order that was in waiting state and after manual check has been declined.

Examples

{
  "event": "order_approved",
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7"
}

{
  "event": "order_declined",
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7"
}

Webhooks for Dunning & Collections

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

Event Name	Description
dunning	Dunning process has been started
promise_to_pay	Debtor stated a promise to pay
instalment_plan	Debtor asked for instalment plan
dispute	Debtor disputed claim
dunning_paused	Dunning process has been paused
archived	Archived cases, mostly unsuccessful
closed	Closed, because of merchant or debtor payment
dca	Case has been handed over to a collection agency

Examples

{
  "event": "dunning",
  "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",
}

Payments

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

Examples

{
  "iban": "DE00000000000123456789",
  "event": "payment",
  "amount": 100.00,
  "order_id": "1234567890",
  "created_at": "2023-07-24 14:19:32",
  "order_uuid": "5ffdc1ad-7898-46f9-b604-499e03b4fcf7",
  "open_amount": 0,
  "invoice_uuid": "03f74b37-3a04-4f76-aa88-221d01520e08",
  "account_holder": "Company Name GmbH"
}

{
  "event": "clawback",
  "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",
}