Getting started with webhook 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 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.
Accounting as a Service provides a dedicated API for administrating Webhooks subscriptions and callback URLs.
Before you start
Before you can receive any notification from Accounting as a Service, you will have to set up an endpoint on your end, where the information can be sent to. Therefore the following steps have to be completed on your end:
-
Setting up an HTTPS-secured endpoint on your side that can receive notifications through POST requests.
-
It is recommended that you whitelist our IPs so that no other other system could access your end-point.
UAT IP : 20.76.134.255, 4.210.170.174
PROD IP : 20.103.56.175, 4.180.187.249
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:
1. Register to AQI
You have to register [here](https://api-explorer-uat.accounting.riverty.io/signup) to get your personal API Key.
Learn more 2. Inform AaaS team about registration
To link your API key to your setup, the API key has to be provided to your contact on Accounting as a Service side.
Learn more 3. Subscribe to the webhook
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"] } ``` ! **IMPORTANT** In case your callback URL is not freely accessible from the internet, please make sure to have a suitable firewall opening in place. Possible **Accounting Notification** Types for your business: - `accounting/EDIErrorSent` for [Qualitative Response](/accounting_as_a_service/documentation/qualitative-response) (**Must be subscribed for Accounting as a Service**) - `accounting/invoiceCreated` for [Invoice Created Notification](/accounting_as_a_service/documentation/invoice-created-notification) - `accounting/documentCreated` for [Document Created Notification](/accounting_as_a_service/documentation/document-created-notification) - `accounting/balanceUpdated` for [Balance Updated Notification](/accounting_as_a_service/documentation/balance-updated-notification) - `accounting/chargebackReceived` for [Chargeback Received Notification](/accounting_as_a_service/documentation/chargeback-received-notification) - `accounting/paymentReceived` for [Payment Received Notification](/accounting_as_a_service/documentation/payment-received-notification) - `accounting/refundCompleted` for [Refund Completed Notification](/accounting_as_a_service/documentation/refund-completed-notification) - `accounting/reminderSent` for [Reminder Sent Notification](/accounting_as_a_service/documentation/reminder-sent-notification) - `accounting/dailyGLAccountBalanceSent` for Daily GL Account Balance 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"] } ```
Learn more 4. Notify Accounting Team about subscription
Inform the team to activate the specific notification in the system.
Learn more 5. Test in UAT environment
Test the notification setup in the UAT environment to ensure everything is working properly.
Learn more Go-Live
After testing, you have to register on the production environment as well (the process is the same but it has to take place in AQI-production environment)
Learn more
Path
POST /notification-callbacks/{callbackId}