Notifications/Webhooks

For certain events, the Nitrobox can send a notification (via webhooks) to another system. Notifications must be activated and set up. Notifications are sent asynchronously. Notifications are used, for example, to pick up an invoice document that has just been generated and make it available to the customer, or to trigger further follow-up processes in a third-party system (e.g. an e-commerce shop).

Setup

You can set up to use our Webhooks via the Webportal. Navigate to Configuration -> Global -> Notifications.

Set up the necessary security configuration, and then specify which event should be POSTed to which of your APIs.

Authentication

NBX uses OAuth2 with client credential flow to authenticate against your configured endpoints. Our Notification Service will send the client_id and client_secret in the Basic Auth header and the trant_type=client_credential in the body with contentType application/x-www-form-urlencoded

Retry policy

If an attempt to send a notification fails, we will attempt to resend the notification with an ever-increasing interval, starting at 2min, increasing the offset by a factor of 4 per attempt. We will make a maximum of 10 attempts with a maximum offset of 12h.
With this set up, the last automatic retry will be attempted about 3 days after the initial failure.

If it still didn't work you will find the notification in the notification log and can trigger the retry manually.

Notification log

In our Webportal under Configuration, -> Global -> Notification you will find a table at the bottom with all notifications attempted to send to your system. You will also find all failed notifications here and can retry them manually.
This can also be used to resend notifications that were previously already sent successfully, in case they got lost in your system for some reason.


Available Notifications

notificationstatustechnical identifierdescription
Customer createdcustomer.createdA new customer record has been created.
Customer updatedcustomer.updatedAn existing customer has been changed.
Address createdaddress.createdA new address record has been created for a customer.
Address updatedaddress.updatedAn existing address record for a customer has been changed.
Order createdorder.createdA new order has been created.
Order updatedorder.updatedAn existing order has been changed.
Order canceledorder.cancelledAn existing order has been canceled.
Contract createdcontract.createdA new contract (subscription) has been created.
Contract updatedcontract.updatedAn existing contract was updated.
Contract renewedcontract.renewedAn existing contract has been extended by the term defined in the plan.
Contract terminatedcontract.terminatedAn existing contract was terminated regularly.
Contract canceledcontract.cancelledAn existing contract was canceled.
Contract expiredcontract.expiredA Contract passes their endDate.
Document createdinvoice.createdA document has been created in the system. This notification is independent of the (PDF) file creation and archiving, which run as an asynchronous process.
Document updatedinvoice.updatedAn already existing document was updated. This essentially refers to meta-information or the document status. In terms of content, documents are unchangeable.
Invoice updatedinvoice.updatedInvoice status changed (e.g. to completed after payment assignment)
Document archivedinvoice.archivedA document has been stored in the file archive and can now be accessed via the file end point.
VAT ID validatedvatId.checkedThe result of a VAT ID validation during the billrun, if activated.
Payment transaction createdpaymentTransaction.createdA new payment transaction has been created.
Payment Intent Resultpaymentintent.resultAn Payment Intent was processed in conjunction with the stored Payment Service Provider.
Payment assignedpaymentAssignment.processedA payment has been assigned to a transaction. Payments can be assigned to a document or an order.
Payment assignment reversedpaymentAssignment.reversedAn assigned payment has been reversed. Payments can be assigned to a document or an order.
Payment assignment processed before settlementpaymentAssignment.processed.beforeSettlementA payment has been assigned to a transaction before settlement receiving. Payments can be assigned to a document or an order.
Payment assignment reversed before settlementpaymentAssignment.reversed.beforeSettlementAn assigned payment has been reversed before the settlement was received. Payments can be assigned to a document or an order.
Settlement createdsettlement.createdA settlement report has been created.
Open item decisionoposCaseDecision.createdAn OPOS case decision has been made. (E.g. with the type discount, or uncollectable receivable)
Opos case updatedOPOS_CASE_UPDATEDOpos case has been updated (e.g. due to payment assignment or open item decision)
Open item decision: reversionoposCaseDecision.reversionAn OPOS case decision has been reversed.
Basware Workflow updatedbasware.workflow.updatedBasware workflow has been created or status has been changed (e.g. to technical accept after business document has been delivered)
Dunning issueddunning.issuedA dunning has been created or a dunning level has been changed.
Dunning archiveddunning.archivedA dunning letter has been stored in the file archive and can now be accessed via the file end point.
Dunning status aggregation updateddunningStatusAggregation.updatedThe highest dunning level of a contract has been changed.
Report createdreport.createdA new report has been created.