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 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)
}

Examples

{
	"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

Invoice State Transitions

Waiting State

Webhooks for Dunning & Collections

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

Payments