For certain events in our platform, instellix can send notifications to external systems. Notifications are delivered via HTTP webhooks and must be explicitly enabled and configured in our platform. Delivery is asynchronous.
Notifications can be used, for example, to retrieve a newly generated invoice document and make it available to a customer, or to trigger downstream processes at your side or in any third-party systems such as e-commerce platforms.
Setup
Navigate to Configuration -> Global -> Notifications. Set up the necessary security configuration, and then specify which event should be sent to which of your webhook endpoints.
Authentication
instellix uses OAuth2 with client credential flow to authenticate against your configured endpoints. Our platform will send the client_id and client_secret in the Basic Auth header and the grant_type=client_credential in the body with contentType application/x-www-form-urlencoded.
Token validity
If the token contains expires_in we expect the value to be provided in seconds according to RFC 6749.
Verify your integration
After completing your security configuration, you can verify that it’s working correctly. To do this, enable the "authentication.verification" notification, then go to the notification web portal and click the button in the top-right corner. This action will trigger a technical notification using your newly configured authentication settings. Finally, check the notification log at the bottom of the page to confirm whether the process succeeded or if any errors occurred.
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 2 ½ days after the initial failure.
We will retry all received status codes of the 4xx and 5xx variants except 400 Bad Request.
If all delivery attempts are exhausted, the notification remains available in the notification log in our web portal. From there, you can manually trigger a retry.
At-least-once Notification Delivery and Duplicate Detection
Webhook notifications are delivered on an at-least-once basis. Due to the nature of distributed systems, communication between systems may occasionally be interrupted or fail. For example, a delivery attempt may time out, a network interruption may occur, or a successful delivery cannot be confirmed.
To ensure that notifications are processed exactly once on your side, every webhook request contains an Idempotency-Key HTTP header. Consumers should store and track previously processed idempotency keys and ignore requests with a key that has already been processed successfully.
The same Idempotency-Key value will be used for all retry attempts and any duplicate deliveries of the same notification.
Notification Log in Webportal
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.
If you find a status code "999", then it is an internal code that is applied if something went wrong, for example, connection timeouts where we didn't receive the response.
Available Notifications
| notification | status | technical identifier | description |
|---|---|---|---|
| Customer created | customer.created | A new customer record has been created. | |
| Customer updated | customer.updated | An existing customer has been changed. | |
| Address created | address.created | A new address record has been created for a customer. | |
| Address updated | address.updated | An existing address record for a customer has been changed. | |
| Order created | order.created | A new order has been created. | |
| Order updated | order.updated | An existing order has been changed. | |
| Order canceled | order.cancelled | An existing order has been canceled. | |
| Contract created | contract.created | A new contract (subscription) has been created. | |
| Contract updated | contract.updated | An existing contract was updated. | |
| Contract renewed | contract.renewed | An existing contract has been extended by the term defined in the plan. | |
| Contract terminated | contract.terminated | An existing contract was terminated regularly. | |
| Contract canceled | contract.cancelled | An existing contract was canceled. | |
| Contract expired | contract.expired | A Contract passes their endDate. | |
| Document created | invoice.created | A 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 updated | invoice.updated | An already existing document was updated. This essentially refers to meta-information or the document status. In terms of content, documents are unchangeable. | |
| Invoice updated | invoice.updated | Invoice status changed (e.g. to completed after payment assignment) | |
| Document archived | invoice.archived | A document has been stored in the file archive and can now be accessed via the file end point. | |
| VAT ID validated | vatId.checked | The result of a VAT ID validation during the billrun, if activated. | |
| Payment transaction created | paymentTransaction.created | A new payment transaction has been created. | |
| Payment Intent Result | paymentintent.result | An Payment Intent was processed in conjunction with the stored Payment Service Provider. | |
| Payment assigned | paymentAssignment.processed | A payment has been assigned to a transaction. Payments can be assigned to a document or an order. | |
| Payment assignment reversed | paymentAssignment.reversed | An assigned payment has been reversed. Payments can be assigned to a document or an order. | |
| Payment assignment processed before settlement | paymentAssignment.processed.beforeSettlement | A payment has been assigned to a transaction before settlement receiving. Payments can be assigned to a document or an order. | |
| Payment assignment reversed before settlement | paymentAssignment.reversed.beforeSettlement | An assigned payment has been reversed before the settlement was received. Payments can be assigned to a document or an order. | |
| Settlement created | settlement.created | A settlement report has been created. | |
| Open item decision | oposCaseDecision.created | An OPOS case decision has been made. (E.g. with the type discount, or uncollectable receivable) | |
| Opos case updated | OPOS_CASE_UPDATED | Opos case has been updated (e.g. due to payment assignment or open item decision) | |
| Open item decision: reversion | oposCaseDecision.reversion | An OPOS case decision has been reversed. | |
| Basware Workflow updated | basware.workflow.updated | Basware workflow has been created or status has been changed (e.g. to technical accept after business document has been delivered) | |
| Dunning issued | dunning.issued | A dunning has been created or a dunning level has been changed. | |
| Dunning archived | dunning.archived | A dunning letter has been stored in the file archive and can now be accessed via the file end point. | |
| Dunning status aggregation updated | dunningStatusAggregation.updated | The highest dunning level of a contract has been changed. | |
| Report created | report.created | A new report has been created. | |
| Authentication verification | authentication.verification | Test your integration without generating any functional data. |