Webhooks Overview

To make tracking important system updates easier, the Mondu platform triggers HTTP webhook notifications sent to your endpoints. These endpoints can be configured through the API, per environment.

If you're new to webhooks, read this guide for more information.

To create a new webhook, simply call POST/webhooks with the topic (see section below) and your endpoint URL as body parameters.

Webhooks Requirements

All endpoints must be configured to receive an HTTP POST with a JSON payload. The webhook system will wait a maximum of 5 seconds for a 2XX HTTP status code in order to mark the payload as delivered. If the endpoint takes longer to respond or an error is returned, the webhook will be re-enqueued for delivery at a later time subject to an exponential backoff - with up to 5 retries.

Error response from your endpoint will result in a retry sequence which will result in multiple submission attempts for the same checkout, and so in such a case of externalReferenceId attribute can be used to uniquely identify the order in your internal schema.

Webhook Object

{
  "topic": "order/confirmed",
  "address": "https://webhook.example.com/order/confirmed"
}

Property	Type	Description
topic	string Values: order/authorized order/confirmed order/pending order/declined invoice/created invoice/payment invoice/late invoice/canceled payout/complete payout/cancelled buyer/accepted buyer/pending buyer/declined billing_configuration/created factoring/approved factoring/pending factoring/declined	The topic for which the system will trigger a notification to the address specified. See Webhooks Events for full list of options
address	string URL	URL of service to which webhook notifications are sent.

Webhooks Events

Mondu webhook payload's top-level structure differs according to the webhook topics.

The full list of webhook topics, their meanings, and event-specific attributes can be found below, detailing what you should expect to receive on your webhook URL endpoint.

Order

If you want to subscribe to all invoice topics, you can do the following:

{
  "topic": "order",
  "address": "https://webhook.example.com/order"
}

order / authorized

{
  "topic": "order/authorized",
  "order_uuid": "031056d3-e0be-4d37-b56a-b4545e1cd5e6",
  "order_state": "authorized",
  "external_reference_id": "order-01",
  "event_time": "2024-02-14T12:45:00.356Z",
  "buyer": {
    "uuid": "61c7a6d3-66aa-4be9-befd-f360b203c819",
    "name": "Mondu B.V.",
    "legal_form": null
  }
}

order / confirmed | pending | declined

{
    "topic": "order/confirmed",
    "order_uuid": "66e8d234-23b5-1125-9592-d7390f20g01c",
    "order_state": "confirmed",
    "external_reference_id": "DE-1-1000745773",
    "event_time": "2023-02-07T15:14:22.301Z",
    "buyer": {
        "uuid": "da696603-deb4-4b5c-8bb3-5cbdb39c3d2c",
        "name": "Max Musterman",
        "legal_form": "Einzelunternehmen"
    },
    "pending_reason_description": "Order value acceptable, manual investigation in progress.", // only shows up with pending orders
    "net_term": 30,
    "bank_account": {
        "account_holder": "Mondu Capital S.à r.l.",
        "bank": "UniCredit Bank - HypoVereinsbank",
        "bic": "HYVEDEMME40",
        "iban": "DE86207300400000000555",
       	"sort_code": "902127", // only for UK buyers
        "account_number": "29823529" // only for UK buyers
    }
}

order / authorized async

{
  "topic": "order/authorized",
  "order_uuid": "031056d3-e0be-4d37-b56a-b4545e1cd5e6",
  "order_state": "authorized",
  "external_reference_id": "order-01",
  "event_time": "2024-02-14T12:45:00.356Z",
  "buyer": {
    "uuid": "61c7a6d3-66aa-4be9-befd-f360b203c819",
    "name": "Mondu B.V.",
    "legal_form": null
  },
  "confirmation_link": "https://portal.mondu.ai/#/buyer/order?token={TOKEN}",
  "payment_method": "invoice",
  "bank_account": {
     "account_holder": "Mondu Capital S.à r.l.",
     "bank": "UniCredit Bank - HypoVereinsbank",
     "bic": "HYVEDEMME40",
     "iban": "DE86207300400000000555",
     "sort_code": "902127", // only for UK buyers
     "account_number": "29823529" // only for UK buyers  
	},
  authorized_net_term: 30
}

order / authorized, async and installment

{
  "topic": "order/authorized",
  "order_uuid": "031056d3-e0be-4d37-b56a-b4545e1cd5e6",
  "order_state": "authorized",
  "external_reference_id": "order-01",
  "event_time": "2024-02-14T12:45:00.356Z",
  "buyer": {
    "uuid": "61c7a6d3-66aa-4be9-befd-f360b203c819",
    "name": "Mondu B.V.",
    "legal_form": null
  },
  "confirmation_link": "https://portal.mondu.ai/#/buyer/order?token={TOKEN}",
  "payment_method": "installment",
  "bank_account": {
     "account_holder": "Mondu Capital S.à r.l.",
     "bank": "UniCredit Bank - HypoVereinsbank",
     "bic": "HYVEDEMME40",
     "iban": "DE86207300400000000555",
     "sort_code": "902127", // only for UK buyers
     "account_number": "29823529" // only for UK buyers  
	},
  "selected_installment_plan": {
    "number_of_installments": 6,
    "minimum_amount_cents": 2000,
    "minimum_amount_formatted": "20,00 €",
    "effective_service_fee_percentage": 10,
    "service_fee_cents": 119,
    "service_fee_formatted": "1,19 €",
    "preliminary_installments": [
      { "installment_number": 1, amount_cents: "10019", amount_formatted: "100,19 €" },
      { "installment_number": 2, amount_cents: "10019", amount_formatted: "100,19 €" },
      { "installment_number": 3, amount_cents: "10019", amount_formatted: "100,19 €" },
      { "installment_number": 4, amount_cents: "10019", amount_formatted: "100,19 €" },
      { "installment_number": 5, amount_cents: "10019", amount_formatted: "100,19 €" },
      { "installment_number": 6, amount_cents: "10024", amount_formatted: "100,24 €" },
    ],
    "is_available": true
  }
}

Note that when issuing "invoice" as a payment method, the actual payment will happen only when the payment of the invoice is completed.

payout / complete | cancelled

{  
  "topic": "payout/paid", // or payout/cancelled
  "payout_uuid": "f174170f-d864-455b-a529-8b4901a3b722",
  "sepa_instruction_id": "23232323232", // this is what they see as reference in their bank statement  
  "amount_cents": 2000, // amount transfered to bank account  
  "external_reference_ids": "['120116-101', '120116-101']", // list of the invoices paid,  
  "event_time": "2021-10-25T14:29:28.643Z"  
}

Invoice

If you want to subscribe to all invoice topics, you can do the following:

{
  "topic": "invoice",
  "address": "https://webhook.example.com/invoice"
}

invoice / created | late | cancelled

The only difference between this payload and the previous one is that it doesnt contain the amount_cents attribute.

{
  "topic": "invoice/created",
  "invoice_uuid": "448ee611-1a20-5937-bc10-1c45bf52116f",
  "order_uuid": "9864d9ac-f870-4b53-a043-c0a3cb8e9358",
  "external_reference_id": "your invoice id",
  "event_time": "2021-10-25T14:29:28.643Z"
}

invoice / payment

The following payload will be provided via this webhook upon invoice payment by the buyer. The payload will be provided for each payment event, both full and partial payments.

{
  "topic": "invoice/payment",
  "invoice_uuid": "448ee611-1a20-5937-bc10-1c45bf52116f",
  "order_uuid": "9864d9ac-f870-4b53-a043-c0a3cb8e9358",
  "external_reference_id": "your invoice id",
  "event_time": "2021-10-25T14:29:28.643Z",
  "amount_cents": 20166 # this means $201.66
}

buyer / accepted | pending | declined

The following payload will be provided via this webhook once buyer onboarding requested is processed.

{
  "topic": "buyer/{TOPIC_NAME}",
  "buyer": {
    "uuid": "66e8d234-23b5-1125-9592-d7390f20g01c",
    "state": "accepted",
    "external_reference_id": "DE-1-1000745773",
    "company_name": "2023-02-07T15:14:22.301Z",
    "first_name": "John",
    "last_name": "Smith",
  }
}

Billing Configuration

billing_configuration/created

{
  "topic": "billing_configuration/created",
  "event_time": "2024-07-03T11:50:50Z",
  "billing_configuration_uuid": "33022e50-079f-4654-91a4-48399d192091",
  "buyer_uuid": "b4bfdb9e-4e24-424d-834a-a3bd30441617",
  "due_in_days": 15,
  "schedule": "monthly",
  "generation_delay_days": 4,
  "payment_method_statement": "bank_transfer"
}

Factoring

factoring/approved

{
  "topic": >"factoring/approved",
  "factoring_uuid": "be5cbc68-b846-4e9a-9e4e-6b709658157d",
  "invoice_external_reference_id": "IN-6c59ba7e8c",
  "factoring_state": "approved",
  "invoice_amount_cents": 20100,
  "payment_method": "invoice",
  "payment_terms": "14",
  "invoice_uuid": "448ee611-1a20-5937-bc10-1c45bf52116f",
  "bank_account": {
    "account_holder": "Mondu Capital S.à r.l.",
    "bank": "UniCredit Bank - HypoVereinsbank",
    "bic": "HYVEDEMME40",
    "iban": "DE86207300400000000555",
    "sort_code": "902127", // only for UK buyers
    "account_number": "29823529" // only for UK buyers
  }
}

factoring/declined

{
  "topic": "factoring/declined",                                                                                  
  "factoring_uuid": "31929c54-5892-4855-8c78-61fd52d0ccdc",                                                       
  "invoice_external_reference_id": "IN-bdb067a615",
  "factoring_state": "declined",
  "invoice_amount_cents":-300,
  "payment_method": "invoice",
  "payment_terms": "14"
}

factoring/pending

{
 "topic": "factoring/pending",
 "factoring_uuid": "14f1fce3-cd73-48ee-9ae6-eb9a83fbdfa3",
 "invoice_external_reference_id": "IN-e06c86d5f3",
 "factoring_state": "manual_review",
 "invoice_amount_cents": 20100,
 "payment_method": "invoice",
 "payment_terms": "14"
}