You can receive notifications from Aria by subscribing to them. They are rather simple. Notification system comes with some concepts.

1. Concepts

1.1 Event

Events are the backbone of the notification system.

A subscription will always be associated to an event.

📘

What if an error occurs ?

We will retry to send the event, indefinitely. This is an alpha feature that will be improved soon.

1.2 Subscription

Subscription is our generic way to design event related notification system. With Subscriptions, you can configure a webhook. You can manage Subscriptions with the API.

We explain Subscription management in the next chapter.

1.3 SubscriptionType

At the moment, we only provide webhook SubscriptionType.

1.4 Invocation

Invocation represents the firing of an event associated to a Subscription. It comes with logs. If your webhooks integration does not seem to work, you may check InvocationLog.

Quirks

In exceptional and rare cases, you may be surprised that one event has been notified to you instead of another. For example, a loan.updated event triggered by a PAYMENT_ORDERED=>TO_REPAY status change could be notified to you before the previous one (ACCEPTED=>PAYMENT_ORDERED). This could be related to the architecture of our event system or external factors. It's quite rare but when it happens, we logically abandon the sending of the previous event.

2. Subscription management

You can manage your Subscriptions using the following endpoints on the API:

• List Subscriptions
• Create new WebHook Subscription
• Update one WebHook Subscription
• Delete one Subscription

3. Managing Aria's responses

Every event is structured like an object with key informations nested under payload.

{
    "date": Date,
    "event": "loan.created",
    "payload": {
        id: string,
        status: string,
        currency: string,
        amount: number,
        beneficiaryIdentifier: Identifier,
        quoteId: string | null,
        invoiceId: string | null,
        receivableId: string | null,
        repaymentReference: string | null,
        attachments: Attachments[],
        createdAt: string,
        acceptedAt: string | null,
        refusedAt: string | null,
        canceledAt: string | null,
        paymentOrderedAt: string | null,
        paymentFailedAt: string | null,
        paymentFailureReasons: Object | null,
        paidAt: string | null,
        repaidAt: string | null,
        dueDate: string,
        payoutLabel: string | null,
        payoutIBAN: string | null,
        activeBlockReasons?: Array<{ code: string; description?: string }> | null,
        refusalReasons?: Array<{ code: string }> | null
    }
}

Validating the webhook payload

When creating a subscription, an optional secret can be provided. It will be used to sign the webhook request payload. You can then validate that Aria is indeed the sender of the request by calculating the signature on your side based on the raw request body, and comparing to the value provided in the x-hub-signature header.

For instance, using Node.js & Express:

const assert = require('node:assert');
const { createHmac } = require('node:crypto');

app.post('/webhook', function (req, res) {
  const expectedSignature = createHmac('sha256', SUBSCRIPTION_SECRET).update(req.body).digest('hex');
  const providedSignature = req.headers['x-hub-signature'];
  assert.equal(expectedSignature, providedSignature, 'Signatures do not match");
  // [...]
  res.status(200).json({})
})

Note that a secret is always generated upon subscription creation and returned in the creation payload.