Open-Notifications: Provider Microservice and Spec

[SebastianStehle]

We just a good about novu and notifo and how we could work together.

One idea that I just had is a spec for provider API. It could be defined as an OpenAPI spec with the following endpoints.

GET /providers
{
    "ses": {
        "name": "Amazon SES",
        "logo": {
            "svg": "...",
            "raster": "base64 encoded
        }
        "types": [
            "Email"
        ],
        "fields": {
            "accessKey": {
            "type": "string",
            "name": { 
                "en": "Access Key",
            },
            "required": true
        },
        "errors": {
            "FOOBAR": "12323"
        }
    } 
}

POST /send
{
    "providerFields": {
        "accessKey": "123" // Can this be encrypted?
    },
    "payloads": [{
        "type": "Email" // discriminator,
        "fromName": "...",
        "fromEmail": "...",
    }]
}

We need a few more endpoints, for example:

1. /verify to verify the settings and credentials.
2. Some providers have asynchronous verification process, e.g. Amazon SES, where you have to prove that you own the email address. Probably the same like the previous endpoint.
3. Some providers have an asynchronous status process, e.g. SMS where the delivery status is sent over a webhook.

Of course this is only an example and needs to be defined later.

Advanced Topics

Service discovery

Services can be discovered by maintaining a list of endpoints. Either...

1. Via configuration
2. Via a central repository and simple json file.

Bulk messages

I guess all messages should be designed for bulk updates, so general performance improvements are possible. If you do not need it it does not make a big difference.

Installation Process

Some providers have an installation process. This is challenging to implement, because it might require some context. For example in telegram you have to install and uninstall a webhook.

Messaging Providers and "bots"

Messaging providers are not that standardized which is a general problem of course. In telegram the user has to initiate the contact with a bot. This is a spam protection. Only then you get the user name that you need to send messages. Some users do not have the username exposed so you have to ask for that: https://github.com/notifo-io/notifo/blob/main/backend/src/Notifo.Domain.Integrations/Telegram/TelegramMessagingSender.cs#L96

In my telegram implementation I directly update the user, which only works because notifo is a monolith: https://github.com/notifo-io/notifo/blob/main/backend/src/Notifo.Domain.Integrations/Telegram/TelegramMessagingSender.cs#L102

Non-stateless response handling

In my Whatsapp integration I bull the status from the Whatsapp API. This turned out to be the most reliable way to get the status: https://github.com/notifo-io/notifo/blob/main/backend/src/Notifo.Domain.Integrations/MessageBird/MessageBirdWhatsAppSender.cs

But it has 2 implications:

1. The provider is not really stateless, which means you cannot shut it down after each message. So deployment via functions would not be possible.
2. The provider needs to call back to the core system via webhook or so.

Theoretically you could add a new endpoint and move the timer to the core, but it probably does not work for all systems. For example if you have a permanent connection with the provider like MQTT it is not sufficient to create and destroy the connection all the time. In general messaging is based on long living connections, which does not match so well to OpenAPI and HTTP.

Evaluation

Advantages

1. Usable for notifo and novu.
2. You can implement you own providers without having to fork the process.
3. You could implement your webhook provider with non-http methods, e.g. GRPC, SOAP or GraphQL and configure it directly in notifo or novu.
4. You can write integrations in multiple programming languages, for example when an SDK is not available for Node or .NET (Notifo).
5. You can use the providers if you send emails yourself without notifo or novu.
6. Providers you provide their own adapters with full code ownership.

Disadvantages

1. Makes the deployment more complicated.
2. How to pass over secrets?
3. Harder to innovate, for example if you want special features for mobile push or so.

[SebastianStehle]

I made my provider interface more clear to understand the abstractions. In this process I have realize the issue with callbacks again.

I tried the same approach that you have in your sms provider:

novu/packages/stateless/src/lib/provider/provider.interface.ts

Line 135 in 3154748

parseEventBody?: (

The trigger (webhook) is from outside and the provider returns a result (or does not return a result). The advantage is the simple request-response model, but for telegram it does not really work:

The webhook is registered once per provider (and no as often per message) and the provider has to handle other messages as well. For example when the user sends a message to the bot you get the chat ID that you need to send messages to the user. This means that the provider basically makes an update of the user, because the chat ID is somehow stored per user.

You could solve this the following way:

IMessagingProvider {
   userProperty(): string; // Like TelegramUsername

   parseEventBody?: (
    body: any | any[],
    identifier: string,
    user: { property: string, ... } // If we find a user with the userProperty()
  ) => IMessagingStatusEvent | IMessagingUserCorrelatedEvent | undefined;
}

But you end up with very specific interfaces and it is unclear whether how good it matches to the general messaging landscape.

Furthermore: If you do not have the control over the channel (e.g. webhook) because the provider uses a GRPC or XMPP, then it does not work anymore. To support all use cases, the provider needs to be able to call the host application in my opinion.

In my SES integration I also use a key value store to bind email addresses to apps (= projects): https://github.com/notifo-io/notifo/blob/main/backend/src/Notifo.Domain.Integrations/AmazonSES/IntegratedAmazonSESIntegration.cs#L186

The goal was to provide integrated email, where the user does not need an account. But such an interface as the key-value-store is also a callback back to the host application.

[scopsy]

I love it! I think that creating a unified and standardized communication API makes a lot of sense to make it much easier to integrate third-party tools. Previously we made a small thing around this with the @novu/stateless library to create a unified set of interfaces for sending messages based on channel types.

I would love to jump on a call to discuss the next action items to make this a reality. I think that creating the base endpoints for the providers for listing, sending and. verifying would be a great starting point for creating a lot of value. We could further create an SDK around it for easier access and just by defining the end supported service such as novu or notifio.