Notifications

Notifications in Accounting as a Service are real-time or scheduled alerts triggered by specific events occurring within the system. The purpose of these notifications is to inform you about important actions, such as updates to customer accounts, errors during data processing, payments, or document creation. These notifications are sent via HTTP POST requests to a URL provided by you during the subscription process.

Notifications

Notifications help ensure you are always up-to-date with key activities, such as receiving feedback on order processing, balance changes, or completed refunds. You can use these notifications to update other internal systems, such as CRM systems, or trigger automated processes, like pausing or reactivating subscriptions.

Request Subscription

You have to subscribe to a notification to receive updates via a webhook. The subscription process involves setting up an endpoint on your side that can receive HTTP POST requests. Follow these steps:

Steps to Subscribe to a Webhook:

1. Subscribe to the Webhook in AQI:

Make a POST request to /administration/v1/notification-callbacks to register your endpoint and the notification types you want to receive.

POST /administration/v1/notification-callbacks HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: XXXX //Your API Subscription Token
Content-Type: application/json

{
    "callbackUrl": "https://your-endpoint.com/notifications", // URL to send notifications
    "notificationTypes": ["accounting/refundCompleted"]
}

Possible Accounting Notification Types for your business:

• accounting/EDIErrorSent (Must be subscribed for Accounting as a Service)
• accounting/invoiceCreated
• accounting/documentCreated
• accounting/balanceUpdated
• accounting/chargebackReceived
• accounting/paymentReceived
• accounting/refundCompleted
• accounting/reminderSent
• accounting/dailyGLAccountBalanceSent

Additional Subscription Notification Types:

• subscriptions/billingInformationAvailable
• subscriptions/expiryWarning
• subscriptions/contractStatusChanged
• subscriptions/authorizationStatus
• subscriptions/billingReturned

Once subscribed successfully, you will receive a 200 (OK) response:

{
    "callbackUrl": "https://your-endpoint.com/notifications",
    "description": "Webhook for receiving refund completed notifications",
    "id": "5b2efc5d-eb64-43eb-99fb-69728c3d2ce0",
    "notificationTypes": ["accounting/refundCompleted"]
}

2. Notify the Accounting Team:

Inform the team to activate the specific notification in the system (except for EDIErrorSent, which is always active).

3. Test in UAT:

Test the notification setup in the UAT environment to ensure everything is working properly.

4. Go Live:

After testing, you can move to production to start receiving notifications.

Notification-Types

Accounting Notifications

EDI Error Sent

• Description: This notification confirms whether a request sent to the accounting interfaces (e.g., create order) was successfully processed or if errors occurred. It provides details about the validation errors, if any.
• Use Case: Helps ensure that all submitted data is validated and processed correctly.
• Details: For more details visit the EDI Error Sent - Notifications - documentation

Please note: This notification is a must-have for every client. A Go-Live without this notification is not possible.

Invoice Created

• Description: Sent when an invoice is successfully generated. Can notify you of invoices created by Accounting as a Service or invoices generated by your system.
• Use Case: Ideal for e-invoicing and reporting to government authorities.
• Details: For more details visit the Invoice Created - Notification - documentation

Document Created

• Description: Notifies you when a document (e.g., invoice, dunning letter) is generated and saved in the system.
• Use Case: Keep track of important documents, download them for the MyAccounting sections or CRM-Tools and access them as needed.
• Details: For more details visit the Document Created - Notification - documentation

Balance Updated

• Description: Informs you about updates to an end-customer's account, such as a new payment received, a new charge, or a chargeback.
• Use Case: Allows you to stay informed of account changes in real-time and keep your internal systems synchronized.

Chargeback Received

• Description: This notification is triggered when a chargeback or failed direct debit is recorded in the settlement file.
• Use Case: Use this information to handle disputed payments and stop subscriptions.
• Details: For more details visit the Chargeback Received - Notification - documentation

Payment Received

• Description: Notifies you when a payment has been successfully booked for an order.
• Use Case: Helps you track incoming payments and manage orders based on payment status.
• Details: For more details visit the Payment Received - Notification - documentation

Refund Completed

• Description: Informs you when a refund has been successfully processed. The refund can be for returns, goodwills, over-payments or cancellations.
• Use Case: Keep your financial systems updated and notify customers that their refund is processed.
• Details: For more details visit the Refund Completed - Notification - documentation

Reminder Sent

• Description: Triggered when an end-customer enters the dunning process or moves up a level in the dunning process.
• Use Case: Allows you to handle subscriptions or orders based on customer payment behavior.The information may be interesting for risk analysis.
• Details: For more details visit the Reminder Sent - Notification - documentation

Subscription Notifications

Billing Information Available

• Description: Notifies you when new billing information is available for a subscription.
• Use Case: Ideal for keeping track of billing cycles and invoicing customers accurately.
• Details: For more details visit the Billing Information Available - Notification - documentation

Expiry Warning

• Description: Sent when a subscription is about to expire.
• Use Case: You can use this to notify customers or trigger renewal offers before the subscription ends.
• Details: For more details visit the Expiry Warning - Notification - documentation

Contract Status Changed

• Description: Informs you when the status of a subscription contract changes (e.g., activated, suspended, canceled).
• Use Case: Helps you manage subscriptions in real-time and take necessary actions for billing or service management.
• Details: For more details visit the Contract Status Changed - Notification - documentation

Authorization Status

• Description: Triggered when the authorization status for a subscription changes (e.g., payment authorization).
• Use Case: Useful for tracking payment authorizations related to recurring subscriptions.
• Details: For more details visit the Authorization Status - Notification - documentation

Billing Returned

• Description: Informs you when a billing attempt is returned or fails.
• Use Case: Helps you manage failed billing attempts and possibly initiate customer communication for corrections.
• Details: For more details visit the Billing Returned - Notification - documentation

List all notification callbacks

To get an overview of all registered notification callbacks, make a GET /administration/v1/notification-callbacks.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request

GET /administration/v1/notification-callbacks HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "351b4bb4-8b0f-470e-83dd-a765d62eba73",
    "callbackUrl": "https://webhook.site/405fb4cfc-4d65-4c23-ac37-e176318baa20",
    "notificationTypes": [
      "accounting/refundCompleted",
      "accounting/documentCreated"
    ],
    "description": "My Test Subscription"
  }
]

Unsubscribing or Modifying a Subscription

To unsubscribe or modify your notification subscriptions, follow these steps:

1. Inform the Accounting Team:

Notify the team to deactivate the specific notification subscription in the system.

3. Unregister the Webhook:

Use the callbackId (received during subscription) to remove the subscription.

DEL /administration/v1/notification-callbacks/{callbackId}