Notifications

How notifications work

With Wicket push notifications, you have the option to receive real-time messages about user data changes. Notifications will come to your HTTPS endpoint.

notifications/user_data_changes_notification_-_Notification_system.jpg

User registers a new account or updates data.
Wicket API sends data to the notification system.
The notification system sends an HTTP(S) request with JSON message in request body to the Customer.
If the Customer response code is 500, the message is redirected to the DLQ (Dead-Letter Queue).

What to do to receive notifications

Step 1: Make sure your API endpoint is ready to process incoming messages

Before you subscribe your HTTP or HTTPS endpoint to a notification topic, you must make sure that your HTTP or HTTPS endpoint has the capability to handle the HTTP POST requests that Wicket uses to send the subscription confirmation and notification messages. Wicket will not send notifications to the endpoint until you confirm the subscription.

Based on the type specified by the header field x-amz-sns-message-type, your code should read the JSON document contained in the body of the HTTP request and process the message. Here are the two primary types of messages:

SubscriptionConfirmation

When Wicket administrator subscribes your HTTP(S) endpoint to the notification topic, you will receive a subscription confirmation POST request. Read the value for SubscribeURL in the request body and visit that URL once in order to confirm the subscription.

Example confirmation request:

Method:

POST / HTTP/1.1

Header:

x-amz-sns-message-type: SubscriptionConfirmation

Body:

{
  "Type" : "SubscriptionConfirmation",
  "MessageId" : "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
  "Token" : "2336412f37f...",
  "TopicArn" : "arn:aws:sns:us-west-2:123456789012:MyTopic",
  "Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:123456789012:MyTopic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:123456789012:MyTopic&Token=2336412f37...",
  "Timestamp" : "2012-04-26T20:45:04.751Z",
  "SignatureVersion" : "1",
  "Signature" : "EXAMPLEpH+...",
  "SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem"
}

Notification

After confirming the subscription you will start receiving notifications -- real-time messages about user data changes. Notification content is in the request body.

Example notification request:

Method:

POST / HTTP/1.1

Header:

x-amz-sns-message-type: Notification

Body:
```
{
    "application_user_sub": "dbf90d14525c8dbf11bcc429b0865e04809507b8e4161fb819",
    "date_time": "2021-05-21T13:47:10.419700",
    "operation_type": "data_update"
}
```

Step 2: Provide your API endpoint information

Send your API endpoint information to Wicket project manager.

Step 3: Confirm the subscription

After Wicket administrator subscribes your endpoint to the notification topic, your endpoint will receive a subscription confirmation message (a POST request). In order to confirm the subscription, you must make a GET request to the location specified by the SubscribeURL in the subscription confirmation message. You can either manually visit the SubscribeURL (for example using a web browser) or send a GET request from you API as a response to the confirmation message. The message can be identified by x-amz-sns-message-type: SubscriptionConfirmation in request headers.

Congratulations! 🎉 Now you will receive notifications.

What to do to retrieve updated user data

Each time a user updates the data, you receive a notification:

{
  "operation_type": "data_update",
  "application_user_sub": "6ab938ba784ecba239696eea64aef245b58563ddb757e7e104",
  "date_time": "2021-05-26T07:29:53.654163"
}

operation_type - identifier of the operation type
application_user_sub - unique user identifier for your application
date_time - date and time when user changed the data

Warning

Please make sure you have access to, and preferably store in your DB, user's application_user_sub. This sub is specific to your application and cannot be included in JWT token or returned by default at login or while getting user data. You or your frontend app need to explicitly request application_user_sub from one of the endpoints: <api_url_profile>/user/reporter/application-user-sub (frontend) or <api_url_b2b>/vendor/user-subs/get (backend).

To get the user data, send an HTTP POST request to <api_url_b2b>/user-data/read with application_user_sub in request body. All api_url_b2b endpoints require x-api-key: <api_key> in request headers.

API Request

POST <api_url_b2b>/user-data/read

Headers

Content-Type: application/json

x-api-key: <api_key>

Body

{
  "application_user_sub": "8ee703ab3e3f1cb294be35048132380d2d1608964deae36e57"
}

API Responses

Status 200: OK

{
  "application_user_sub": "8ee703ab3e3f1cb294be35048132380d2d1608964deae36e57",
  "user_data": {
    "is_club": "true",
    "club_id": "41",
    "email": "dev-esa-01@yopmail.com"
  },
  "user_agreements": []
}

Description: success

Status 400: Bad Request

{
  "status": 400,
  "message": "BAD_REQUEST"
}

Description: Malformed request

Status 403: Forbidden

{
  "message": "Forbidden"
}

Description: Incorrect or missing API key

Status 404: Not Found

{
  "status": 404,
  "error_fields": "USER_NOT_FOUND"
}

Description: Incorrect application_user_sub

Curl example

curl -X 'POST' \
  'https://<wicket api url>.com/b2b/user-data/read' \
  -H 'accept: application/json' \
  -H 'X-API-Key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "application_user_sub": "<application_user_sub>"
}'