Use the Notification API to notify your applications when a specific event occurs. To enable notifications, you must:

1. Create a subscription for a specific set of events and an application.

2. Periodically send requests to determine if there are any new notifications for the subscription.

The Notification API also contains an API for deleting a subscription (unsubscribe) as well as fetching statistical information about a subscription. It supports the v2 events that are configured in the events list.

API-security

All endpoints of this API are protected; they can only be used if a valid OAuth access token is provided along with a valid authorization scope.

Typical flow

The typical flow for using this API is:

1. Contact OneWelcome to register a client application for the Notification API.

2. OneWelcome provides a client id and client secret and configures a notification:consent:consumer scope for the application.

3. OneWelcome configures a notification:consent:administrator scope to enable a notification administrator to manage subscriptions.

4. The notification administrator uses an Oauth2/OIDC flow to create a subscription for the client id (application), using the notification subscription endpoint.

5. A customer application uses Oauth2/OIDC endpoints to obtain an access token. To receive notifications, the access token must contain the notification:consent:consumer scope.

6. The customer application repeatedly invokes the notifications endpoint to obtain updates.

7. The notification administrator unsubscribes the client id (application) when notifications are no longer needed.

Choose a server: www.onewelcome.com

Authentication

OAuth2

Flow: Authorization code

Token URL: https://example-domain-uri.com/auth/oauth2.0/v1/token

Authorization URL: https://example-domain-uri.com/auth/oauth2.0/v1/authorize

Scope:

• notification:consent:administrator - Allows an administrator to create and delete subscriptions

• notification:consent:consumer - Allows a user to retrieve subscriptions and notifications

Notification subscription v1

Subscribe to notifications for events

Use this API to create a subscription containing:

• client id
• event ids

Whenever an event is generated that includes an id in the list sent in the request, it will be available to the notifications endpoint.

The response contains information about the subscription just created, including the subscription id which can be used to get notifications.

Auth

OAuth2

Scope: notification:consent:administrator

Request: application/vnd.iwelcome.v1+json

Example request

curl --request POST \
 --url 'https://www.iwelcome.com//notification/v1/subscriptions' \
 --header 'Authorization: Bearer {token}' \
 --data '{
  "event_type_ids": [
    "{array[string]...}"
  ],
  "client_id": "{string}"
}'

Responses: application/vnd.iwelcome.v1+json

Example response

 201 Successfully subscribed to resources
 400 Bad request, error codes: NOT000001, NOT000009
 401 Authorization failure, error code: NOT000008
 403 Permissions denied, error code: NOT000007
 404 client_id not found, error code: NOT000002
 409 Duplicate Registration, error code: NOT000003
 429 Too many requests, error code: NOT000004
 500 Internal server error, error code: NOT000005
{
 "id": "{string}",
 "subscription": {
  "client_id": "{string}",
  "event_type_ids": [
   "{array[string]...}"
  ],
  "subscribed_by": "ed7afb3e75e8482db1cab4e2950ae50c  or notificationAdminApp.",
  "subscription_date": "2018-01-23T04:56:22Z",
  "notification_url": "{string}",
  "notification_page_size": "{integer}"
 },
 "subscription_status": "{}"
}

Get the details of a subscription

Use this endpoint to get:

• Static details of a subscription
• Time that notifications were last retrieved from a subscription
• 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 different values.

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.

Auth

OAuth2

Scope: notification:consent:consumer

Path parameters

Example request

curl --request GET \
 --url 'https://www.iwelcome.com//notification/v1/subscriptions/{id}' \
 --header 'Authorization: Bearer {token}'

Responses: application/vnd.iwelcome.v1+json

Example response

{
 "id": "{string}",
 "subscription": {
  "client_id": "{string}",
  "event_type_ids": [
   "{array[string]...}"
  ],
  "subscribed_by": "ed7afb3e75e8482db1cab4e2950ae50c  or notificationAdminApp.",
  "subscription_date": "2018-01-23T04:56:22Z",
  "notification_url": "{string}",
  "notification_page_size": "{integer}"
 },
 "subscription_status": "{}"
}

Unsubscribe notifications

Use this endpoint to unsubscribe from notifications for a set of events.

Auth

OAuth2

Scope: notification:consent:administrator

Path parameters

Example request

curl --request DELETE \
 --url 'https://www.iwelcome.com//notification/v1/subscriptions/{id}' \
 --header 'Authorization: Bearer {token}'

Responses: application/vnd.iwelcome.v1+json

No response.

Notification retrieval v1

Retrieves notifications for the events to which the client subscribed.

Use this to retrieve a set of notifications for a subscription.

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.

Auth

OAuth

Scope: notification:consent:consumer

Path parameters

Example request

curl --request GET \
 --url 'https://www.iwelcome.com//notification/v1/subscriptions/{id}/notifications' \
 --header 'Authorization: Bearer {token}'

Responses: application/vnd.iwelcome.v1+json

Example response

{
 "page": "{integer}",
 "size": "{integer}",
 "results": [
  {}
 ]
}