Your suggested change has been received. Thank you.

close
Thales Logo

All

  • All
redocly logoAPI docs by Redocly

Notification API (0.1)

Download OpenAPI specification:Download

Notification API can be used to notify customers applications when a certain event happens in the system. In order for a customer to get notifications, certain actions should be performed, such as creating a subscription for a required set of events and an application, and then periodically send requests to see if there are any new notifications for a specific subscription. This API also contains an API for deleting a subscription (unsubscribe) as well as getting statical information about a specific subscription. It supports the v2 events that are configured in events list. API-security All endpoints of this API are protected endpoints; they can only be used if a valid OAuth 'access token' is provided. The access token need to be associated with the valid authorisation 'scope'. Scopes that are relevant for this API are: - notification:consent:administrator: Allows to create and delete subscription - notification:consent:consumer: Allows to retrieve subscriptions and notifications

Typical flow The typical flow for using this API is:

  • iWelcome customer contacts iWelcome to register a client application for using the notification API. iWelcome provides customer with client id and client secret and configures the scope 'notification:consent:consumer' for this app, identified by client id
  • For the notification administrator to manage the subscriptions, a new client with scope 'notification:consent:administrator' is configured
  • The notification administrator creates a subscription for the client id (application), using the notification subscription endpoint. Creating a new subscription requires the 'notification:consent:administrator' scope which can be obtained by any Oauth2/OIDC flow
  • The notification consumer (customer application) uses Oauth2/OIDC endpoints to obtain an access token that can be used for the notification API. In order to be able to get notifications the access token has to contain the 'notification:consent:consumer' scope
  • The notification consumer (customer application) repeatedly invokes the 'notifications' endpoint to obtain notifications
  • The notification administrator can unsubscribe the client when notifications are no longer needed by that client

Notification subscription V1

Subscribe to notifications for any events

This API can be used to create a new subscription. While creating a new subscription, a list of event ids and a client id should be provided. Whenever there will be a new event generated in the system with an id which is in the list sent on the request, the event will be also available when calling the 'notifications' endpoint. The response of this API contains some information about the newly created subscription along with the subscription id which can be later on used to get the notifications. In order to be able to access this API, 'notification:consent:administrator' scope is required.

Authorizations:
OAuth2
Request Body schema: application/vnd.iwelcome.v1+json

Create new subscription request

event_type_ids
required
Array of strings non-empty non-empty unique

The list of events to subscribe for notifications

client_id
required
string^[\p{L}0-9\._\-]+$

The oauth2 client identifier issued to the client during the registration process, as indicated by OAuth RFC 6749.

Responses

Request samples

Content type
application/vnd.iwelcome.v1+json
{
  • "event_type_ids": [
    ],
  • "client_id": "string"
}

Response samples

Content type
application/vnd.iwelcome.v1+json
{
  • "id": "string",
  • "subscription": {
    },
  • "subscription_status": {
    }
}

Get the details of a subscription

This endpoint can be used to get the 'static' details of a subscription. Also the last time notifications were retrieved from the subscription is returned as well as the number of remaining notifications. The number of remaining notifications is a dynamic number since new notifications may be added constantly. Two consecutive calls to this endpoint may return a different value this number. In order to be able to access this API, 'notification:consent:consumer' scope is required. The endpoint will only return the subscription if the access token sent on the request has, apart from the required scope mentioned above, the same client_id that was used to create the subscription identified with the id sent in the url.

Authorizations:
OAuth2
path Parameters
id
required
string^[\p{L}0-9\._\-]+$

Subscription id

Responses

Response samples

Content type
application/vnd.iwelcome.v1+json
{
  • "id": "string",
  • "subscription": {
    },
  • "subscription_status": {
    }
}

Unsubscribe notifications

Clients can use this endpoint to unsubscribe from notifications for a set of events. In order to be able to access this API, 'notification:consent:administrator' scope is required.

Authorizations:
OAuth2
path Parameters
id
required
string^[\p{L}0-9\._\-]+$

Subscription id

Responses

Response samples

Content type
application/vnd.iwelcome.v1+json
{
  • "code": "NOT000001",
  • "description": "string"
}

Notification retrieval V1

Retrieves notifications for the events that the client subscribed to

'Retrieve a set of notifications of a subscription identified by a unique id. In order to be able to access this API, 'notification:consent:consumer' scope is required. The endpoint will only return the subscription if the access token sent on the request has, apart from the required scope mentioned above, the same client_id that was used to create the subscription identified with the id sent in the url. Once a notification is retrieved, the same notification cannot be retrieved again for the same subscription. This means that this endpoint is NOT idempotent according to REST-definitions. Clients need to retrieve the notifications on a regular (e.g. daily) basis. Notifications will not be kept indefinitely, but it will be kept for a configurable amount of time which is set by default to 6 hours. The schema for these resources depend on the eventIds to which the client has subscribed to.

Authorizations:
OAuth2
path Parameters
id
required
string^[\p{L}0-9\._\-]+$

subscription id

Responses

Response samples

Content type
application/vnd.iwelcome.v1+json
{
  • "page": 0,
  • "size": 0,
  • "results": [
    ]
}