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.

Webhook Topics

If you want to subscribe to any of the topics, call Create Webhook with following payload:

{
  "topic": "{{Topic}}",// or {{Topic}}/{{Subtopic}} i.e order/confirmed
  "address": "https://webhook.example.com/order/confirmed"
}

Topic/Subtopic	Event Description
order	Mondu sends the payload upon each order event listed below:
order/authorized	Buyer authorized the order.
order/confirmed	Mondu accepted the order.
order/pending	Mondu will manually review the order. Do not ship.
order/declined	Mondu declined the order.
order/canceled	Merchant canceled the order.
invoice	Mondu sends the payload upon each invoice event listed below:
invoice/created	Invoice submitted to Mondu.
invoice/payment	Mondu reconciled any bank transfer from buyer.
invoice/late	Buyer did not pay the invoice on time.
invoice/canceled	Merchant cancelled the invoice.
invoice/complete	Invoice reached outstanding amount 0. It can be caused by reconciliation of a bank transaction or any nettable entity like credit note etc.
invoice/reopened	Mondu unreconciled the invoice in case the payment is linked by mistake or the direct debit is rejected.
payout	Mondu sends the payload upon each payout event listed below:
payout/complete	Mondu paid out merchant.
payout/cancelled	Mondu cancelled payout.
buyer	Mondu sends the payload upon each buyer event listed below:
buyer/accepted	Mondu accepted the buyer.
buyer/pending	Mondu will manually review the buyer.
buyer/declined	Mondu declined the buyer.
buyer/limit_updated	Mondu updated buyer limit.
factoring	Mondu sends the payload upon each factoring event listed below:
factoring/approved	Mondu approved the factoring.
factoring/pending	Mondu will manually review the factoring.
factoring/declined	Mondu declined the factoring.
kyc	Mondu sends the payload upon each KYC event listed below:
kyc/approved	Mondu approved the KYC.
kyc/pending	Mondu will manually review the KYC.
kyc/declined	Mondu declined the KYC.

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.

Webhooks Security

Whitelist IP Addresses

All endpoints are strongly encouraged to use HTTPS, as this protects the payload in transit. Mondu sends the hooks from the IPs below, so make sure they are whitelisted in your organization’s infrastructure:

Sandbox: 3.67.101.172, 3.69.55.142, 3.72.30.70, 34.159.77.21
Production: 3.68.36.187, 3.127.195.5, 18.194.230.169, 34.185.141.246

Compare Signature

To verify that a webhook was actually sent by Mondu, every payload is signed with a signature that is passed through as the HTTP header x-mondu-signature. The signature is Hex encoded and can be replicated by applying HMAC-SHA-256 to the body of the webhook with your specific webhooks’ secret, which can be requested via Get Webhook Keys API endpoint.

After receiving the message, your app should verify the HMAC signature by attempting to re-create the signatures by hashing the raw message body with the webhooks’ HMAC secret.
To verify the signature:

Extract the text of the UTF-8 payload as an array of bytes (including line endings)
Compute a SHA256 HMAC digest for the array of bytes with the secret (retrieved from the secret webhooks’ endpoint GET /webhooks/keys)
Base64-encode each of the digests
Compare the base64 digest(s) to the values of the x-mondu-signature headers

The code example below demonstrates the process of implementing this message authenticity check:

const crypto = require('crypto')
module.exports = class MonduVerifier {
    constructor(secret) {
        this.secret = secret
    }

    verify(payload, signature) {
        var signaturePayload = crypto
            .createHmac('sha256', secret)
            .update(payload)
            .digest('hex')

        if (signaturePayload == signature) {
            return true
        } else {
            return false
        }
    }
}

var MonduVerifier = require('./mondu_verifier.js')
var verifier = new MonduVerifier(secret)
verifier.verify(payload, signature)

Webhooks Attempts Examples

Order

{
  "topic": "order/authorized",
  "order_uuid": "414e7c34-cfbf-418b-8913-86dc1d68b710",
  "order_state": "authorized",
  "external_reference_id": "your-order-id-4d98bbcf-674a-4342-8b38-d6411aa04fb3",
  "event_time": "2025-11-13T07:17:04.416954114Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  }
}

{
  "topic": "order/pending",
  "order_uuid": "414e7c34-cfbf-418b-8913-86dc1d68b710",
  "order_state": "pending",
  "external_reference_id": "your-order-id-4d98bbcf-674a-4342-8b38-d6411aa04fb3",
  "event_time": "2025-11-13T07:18:23.333837919Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  }
}

{
  "topic": "order/confirmed",
  "order_uuid": "414e7c34-cfbf-418b-8913-86dc1d68b710",
  "order_state": "confirmed",
  "external_reference_id": "your-order-id-4d98bbcf-674a-4342-8b38-d6411aa04fb3",
  "event_time": "2025-11-13T07:21:47.663120627Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  },
  "net_term": 30,
  "bank_account": {
    "account_holder": "Mondu Capital S.à r.l.",
    "iban": "DE92207300402000003398",
    "bank": "UniCredit Bank - HypoVereinsbank",
    "bank_name": "unicredit",
    "bic": "HYVEDEMME40"
  }
}

{
  "topic": "order/declined",
  "order_uuid": "c5af4947-1ab9-429d-94de-25f8b3fb7d71",
  "order_state": "declined",
  "external_reference_id": "your-order-id-bc85d808-c818-4831-9e93-9d3c41af87f5",
  "event_time": "2025-11-13T07:25:56.625378954Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  }
}

Async Order

{
  "topic": "order/authorized",
  "order_uuid": "73fcd70e-c3c2-495b-9310-2087ad7ad0e0",
  "order_state": "authorized",
  "external_reference_id": "your-order-id-2e8abd33-a0d1-4740-a5b6-e27cf76cbea5",
  "event_time": "2025-11-13T07:28:19.910709914Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  },
  "confirmation_link": "https://portal.demo.mondu.ai/#/buyer/order?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjcmVhdGVkX2F0IjoiMjAyNS0xMS0xMyAwNzoyODoxOSBVVEMiLCJleHAiOjE3NjM3MTAwOTksIm9yZGVyX2lkIjo3MTc5OSwic2Vzc2lvbiI6ImU2OTBhMmE5LTUyZjYtNDJiMS1iMjQ0LTg0NGZiYTA0NTFhZSJ9.Ps38CW4928g1IMCHwRqztbQXfv-Ox5igOzqbgeJiWAY",
  "bank_account": {
    "account_holder": "Mondu Capital S.à r.l.",
    "iban": "DE92207300402000003398",
    "bank": "UniCredit Bank - HypoVereinsbank",
    "bank_name": "unicredit",
    "bic": "HYVEDEMME40"
  }
}

{
  "topic": "order/pending",
  "order_uuid": "73fcd70e-c3c2-495b-9310-2087ad7ad0e0",
  "order_state": "pending",
  "external_reference_id": "your-order-id-2e8abd33-a0d1-4740-a5b6-e27cf76cbea5",
  "event_time": "2025-11-13T07:27:37.346370632Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  }
}

{
  "topic": "order/confirmed",
  "order_uuid": "73fcd70e-c3c2-495b-9310-2087ad7ad0e0",
  "order_state": "confirmed",
  "external_reference_id": "your-order-id-2e8abd33-a0d1-4740-a5b6-e27cf76cbea5",
  "event_time": "2025-11-13T07:33:48.433353482Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  },
  "net_term": 30,
  "bank_account": {
    "account_holder": "Mondu Capital S.à r.l.",
    "iban": "DE92207300402000003398",
    "bank": "UniCredit Bank - HypoVereinsbank",
    "bank_name": "unicredit",
    "bic": "HYVEDEMME40"
  }
}

{
  "topic": "order/declined",
  "order_uuid": "58ca86fb-9580-4fae-9f35-c97639096857",
  "order_state": "declined",
  "external_reference_id": "your-order-id-abadb23d-ee7c-440e-a207-91cf27f9ce72",
  "event_time": "2025-11-13T07:40:15.51849104Z",
  "buyer": {
    "uuid": "6960ff5c-84fc-4115-8f18-905dca8b6a8c",
    "name": "Mondu GmbH",
    "legal_form": "GmbH"
  }
}

Buyer

{
  "topic": "buyer/limit_updated",
  "buyer": {
    "uuid": "66e8d234-23b5-1125-9592-d7390f20g01c",
    "external_reference_id": "DE-1-1000745773",
    "purchasing_limit_cents": "10000",
    "balance_cents": "100",
    "max_collections_state": "no",
    "max_purchase_value_cents": "9000"
  }
}

{
  "topic": "buyer/accepted",
  "buyer": {
    "uuid": "66e8d234-23b5-1125-9592-d7390f20g01c",
    "state": "accepted",
    "external_reference_id": "DE-1-1000745773",
    "company_name": "Mondu GmbH",
    "first_name": "John",
    "last_name": "Smith",
  }
}

Payout

{  
  "topic": "payout/complete", // 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

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

{  
  "topic": "invoice/complete",  
  "invoice_uuid": "uuid",  
  "order_uuid": "uuid",  
  "external_reference_id": "your invoice id",  
  "event_time": "2021-10-25T14:29:28.643Z",  
  "gross_amount_cents": 20  
}

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

Billing Configuration

{
  "topic": "billing_configuration/created",
  "schedule": "monthly",
  "buyer_uuid": "0d7a322d-fce3-45e5-b2f5-5e2e0431e2da",
  "event_time": "2025-11-15T10:53:38Z",
  "due_in_days": 15,
  "generation_delay_days": 1,
  "payment_method_statement": "bank_transfer", // or direct_debit
  "billing_configuration_uuid": "43fa0a11-f5c4-4377-8bb9-9a8786ba6fba"
}

Factoring

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

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

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

KYC

{
  "topic": "kyc/accepted",
  "buyer": {
    "uuid": "66e8d234-23b5-1125-9592-d7390f20g01c",
    "kyc_state": "accepted",
    "external_reference_id": "DE-1-1000745773",
  }
}