The YOUnite Notification Service notifies consumers about events in the Federated System, including changes to metadata (such as Zones, Domains, etc) and changes to data records.

Introduction

image

There are two types of notification messages:

  1. Metadata notifications: Changes in YOUnite resources such as Zones, Domains, Users, Groups, Roles, etc.

  2. Data event notifications: Data events, just like those sent to adaptors indicating a record was added, updated or deleted.

Consumers register for the notifications they are interested in. As events occur that match the registration, they are delivered in near real-time to a destination. Two types of destinations are supported:

  1. Webhook - an HTTP endpoint that accepts a POST with the message in the body of the request.

  2. Websocket - a TCP connection with a client, such as a web browser. Websockets are used by the YOUnite UI to update itself as metadata changes occur and to monitor events in real-time.

Message Formats

Messages are delivered to their destination as JSON encoded Strings.

Metadata Notifications

Metadata notifications include:

  1. action = POST, PUT, PATCH, DELETE

  2. resource = absolute URI of the resource

  3. type = resource type

  4. data = resource’s data

Example:

{
    "action": "POST",
    "resource": "/zones/a1b5e00a-819e-4106-b169-8465f5088a78",
    "type": "Zone",
    "data": {
        "name": "New Zone",
        "zoneUuid": "a1b5e00a-819e-4106-b169-8465f5088a78",
        ... etc ...
    }
}

Data Notifications

Data Notifications include:

  1. action = POST, PUT, DELETE

  2. drUuid = DR’s UUID

  3. domainVersionUuid = Domain Version UUID

  4. sourceAdaptorUuid = Source Adaptor UUID

  5. destinationAdaptorUuid = Destination Adaptor UUID

  6. transactionUuid = Unique identifier of the transaction

  7. createTime = Time in milliseconds when the notification was created

  8. drKey = DR Key of the record

  9. jsonData = JSON-encoded string with the data

Example:

{
    "action": "POST",
    "drUuid": "4eed56f2-db3c-4f86-b6f8-77d85301b3da",
    "domainVersionUuid": "5b9c2ee9-9a39-413d-b055-43ad394f93c1",
    "sourceAdaptorUuid": "5e354033-a5cd-4374-9fde-5df0a21cdc02",
    "destinationAdaptorUuid": "d397b22f-f55b-46d6-915c-8f880fb76f4b",
    "transactionUuid": "8cf7b494-e02e-4fac-af96-d439c6c49417",
    "createTime": 1593710619478,
    "drKey": "[\"abc123\"]",
    "jsonData": "{\"customerId\":\"abc123\",\"name\":\"Testo McTesterson\"}"
}

Metadata Webhook Registrations

Users with permission may register for metadata notifications for endpoints they have access to. To be able to register for a notification to a resource, the user must have GET permission for that resource. See Notifications API for details on the REST API for creating, updating and removing registrations.

Note
 This applies to metadata notifications only. See below for data event notifications.

Metadata Notification Registration format

Example:

{
	"callback": "https://server/endpoint",
	"callbackType": "WEB_HOOK",
	"httpHeaders": [
		{
			"name": "header1",
			"value": "value1"
		}
	],
	"oauth2Registration": {
		"authorizationUri": "(authorization uri)",
		"tokenUri": "(token uri)",
		"jwkSetUri": "(jwk set uri)",
		"issuerUri": "(issuer uri)",
		"clientId": "(client id)",
		"clientSecret": "(client secret)",
		"clientAuthenticationMethod": "basic",
		"authorizationGrantType": "client_credentials",
		"scope": "email,username"
	},
	"events": [
		{
			"resource": "/domains/*",
			"actions": [
				"POST",
				"PUT",
				"DELETE"
			]
		},
		{
			"resource": "/zones/?/adaptors/?",
			"actions": [
				"ALL"
			]
		}
	]
}
Registration fields
Name Description Required Example

callback

URL to send messages to

Yes

https://server/endpoint

callbackType

Must be WEB_HOOK

Yes

WEB_HOOK

events

List of events to listen for

Yes

(see below)

httpHeaders

Optional HTTP headers in the form of an array of name/value pairs to send with the request

No

Authorization: Bearer xxx

oauth2Registration

OAuth2 authentication information

No

(see below)
Event fields
Name Description Required Example

resource

Resource string with wildcards*

Yes

/zones/?

actions

List of actions

Yes

[ "POST", "DELETE" ]

*Two wildcards are used in resource strings. The ? indicates any child resource but not grandchildren. The * indicates any child resource and its grandchildren.

OAuth2 Registration Fields
Name Description Example

authorizationUri

Authorization URI for the provider

tokenUri

Token URI for the provider

jwkSetUri

JWK set URI for the provider

issuerUri

URI that can either be an OpenID Connect discovery endpoint or an OAuth 2.0 Authorization Server Metadata endpoint defined by RFC 8414.

clientId

Client ID

clientSecret

Client Secret

clientAuthenticationMethod

Client authentication method.

basic

authorizationGrantType

Authorization grant type. This is typically client_credentials.

client_credentials

scope

Authorization scopes, delimited by commas. When left blank the provider’s default scopes, if any, will be used.

email
Open ID Connect Configuration

Open ID Connect makes configuration much easier for OAuth2. If the OAuth2 providers supports Open ID Connect the following are typically the only fields that need to be configured:

  1. issuerUri - This can be found in the issuerUri field in the discovery document endpoint of the Open ID Connect compatible server.

  2. clientId - The client id or username

  3. clientSecret - The client secret or password

  4. authorizationGrantType - Typically this needs to be set to client_credentials.

See Spring Boot OAuth2 Client for more details regarding configuration of Spring Boot OAuth2 clients.

Testing Webhooks

The website webhook.site is a useful tool to test webhooks. When you visit the website, it will assign you a unique URL which you put in the callback field of the registration.

Example:

PUT /notifications

{
	"callback": "https://webhook.site/88f1af6d-b7e2-4769-bec5-18327b8bff8e",
	"callbackType": "WEB_HOOK",
	"events": [
		{
			"resource": "/domains/*",
			"actions": [
				"POST",
				"PUT",
				"DELETE"
			]
		},
		{
			"resource": "/zones/?/adaptors/?",
			"actions": [
				"ALL"
			]
		}
	]
}

This will create a registration that will deliver:

  1. All POST, PUT and DELETE events on domains and any child resources (such as domain versions).

  2. All Data Record changes that the user has access to. To target specific resources, any of the ? wildcards should be replaced with the UUID of the resource.

Data Event Webhook Registrations

Unlike metadata registrations, users cannot directly register for data event notifications. Instead, a "virtual adaptor" can be created as a destination for data events which routes these data events to the notification service.

This virtual adaptor acts exactly like any other adaptor (including apply data governance), but instead of routing messages to an actual adaptor it routes its messages to the notification service for delivery to the web hook destination.

To configure a virtual adaptor for webhooks:

  1. Use the Web Hook Adaptor adaptor type when creating the adaptor. To find the UUID of this adaptor type, do a GET /adaptor-types.

  2. Include the domain/versions for data events the adaptor should receive.

  3. Configure the metadata of the adaptor with webhook information. See the example below.

  4. Optionally add data governance to further control what data events go to the webhook.

Example:

POST /zones/d8686909-1f77-4e90-9231-d40bb78f8cc7/adaptors

{
	"name": "Test Webhook Adaptor",
	"adaptorTypeUuid": "3f78d8b4-c3ab-4c54-8224-61358c384fbe",
	"capabilities": [
		{
			"domainName": "customer",
			"versionNumber": 1,
			"action": "POST"
		},
		{
			"domainName": "customer",
			"versionNumber": 1,
			"action": "PUT"
		},
		{
			"domainName": "customer",
			"versionNumber": 1,
			"action": "DELETE"
		}
	],
	"metadata": {
		"url": "https://server/endpoint",
		"httpHeaders": [
			{
				"name": "header1",
				"value": "value1"
			}
		],
		"oauth2Registration": {
			"authorizationUri": "(authorization uri)",
			"tokenUri": "(token uri)",
			"jwkSetUri": "(jwk set uri)",
			"issuerUri": "(issuer uri)",
			"clientId": "(client id)",
			"clientSecret": "(client secret)",
			"clientAuthenticationMethod": "basic",
			"authorizationGrantType": "client_credentials",
			"scope": "email,username"
		}
	}
}

Metadata fields

Name Description Required Example

url

URL to send messages to

Yes

https://server/endpoint

httpHeaders

Optional HTTP headers in the form of an array of name/value pairs to send with the request

No

Authorization: Bearer xxx

oauth2Registration

OAuth2 authentication information

No

See OAuth2 Registration Fields

See OAuth2 Registration Fields for information about OAuth2 configuration