## Subscribing to a topic <a name="create-subscription"></a>
The consumer uses the data notification Subscription API to create a Subscription for the topic of interest. A subscription id is returned in the response that can be used to get the subscription details again or delete the subscription later.
```
POST /api/register/v1/subscription/
```
To subscribe to a topic, consumers must have a "https" endpoint supporting both "GET" and "POST" methods. "GET" is used as a challenge endpoint when creating (or updating) a subscription to validate that consumer owns this endpoint. "POST" is used for pushing the notifications to consumers.
The challenge is performed only when creating a subscription or when [Updating secret for a Subscription](#update-subscription)
Below are the details of the two types of Subscriptions and the challenge process:
#### Hash-based Message Authentication Code (HMAC) Subscription using a "secret" string <a name="create-hmac-subscription"></a>
Before creating an HMAC Subscription, the consumer needs to make sure that "GET" is supported on the endpoint being registered with DE Notification and the endpoint accepts query parameters named "crc" & "hmac". DE Notification will send a "GET" request on this endpoint with a random crc, and expects a response hash generated using the crc & the secret value (i.e. "testSecret" in the example above).
In addition, consumers may also want to validate the hmac field, which is the signature that will be used when a message is pushed to this endpoint. The signature verification must be used in the push endpoint implementation before processing the messages, to ensure that the message is coming from OSDU Notification.
Note: Secret value may not contain any special characters (only alphanumeric characters) and the number of characters must be even.
<details><summary>Sample API definition for setting up the challange end point</summary>
```
...
paths:
...
...
'/consumer':
get:
summary: Notification "get" API
consumes:
- application/json
produces:
- application/json
parameters:
- in: query
name: crc
type: string
required: true
- in: query
name: hmac
type: string
required: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/challengeResponse'
...
...
definitions:
challengeResponse:
type: object
required:
- schema
properties:
responseHash:
type: string
```
</details>
<details><summary>Sample Java code to generate the hmac signature, validate it and send a response with hash</summary>
```
...
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
....
@GET
@Path(<DomainEndpoint>)
public Response challenge(@QueryParam("crc") @NotBlank String crc,
@QueryParam("hmac") @NotBlank String hmac) {
// Use the secret you send to the subscriber registration create request
// Hint: Secret string can be stored as configuration for the service
Before creating a GSA Subscription, the consumer needs to make sure that "GET" is supported on the endpoint being registered with DE Notification and it accepts a query parameter named "crc". DE Notification will send a "GET" request on this endpoint with a random crc, and expects a response hash generated using crc & the private_key_id field from the Service account used for subscription.
In addition, consumers may also want to validate the google id token provided as "authorization" header, which will be generated using the audience & key provided. The google id token must be used in the push endpoint implementation before processing the messages, to ensure that the message is coming from OSDU Notification.
<details><summary>Sample API definition for setting up the challange end point</summary>
```
...
paths:
...
...
'/consumer':
get:
summary: Notification "get" API
consumes:
- application/json
produces:
- application/json
parameters:
- in: query
name: crc
type: string
required: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/challengeResponse'
...
...
definitions:
challengeResponse:
type: object
required:
- schema
properties:
responseHash:
type: string
```
</details>
<details><summary>Sample Java code to validate the google id token and send a response with hash</summary>
Please note that each message can contain a maximum of 50 record updates and can have updates for multiple kinds and operations. If there are more than 50 record updates, subscribers will receive multiple messages.
Possible values of operation types (i.e. "op" field in above example) are as follows:
- create
- delete
- create_schema
### Notification handler endpoint - HMAC Secret type
Endpoints with HMAC Subscriptions must accept a parameter named "hmac", which has a signature, as described above. Consumer should make sure to validate this signature before processing messages in request body.
<details><summary>A simple API definition to receive notifications </summary>
```
...
'/consumer':
post:
summary: Receive notification
description: "Receives push notification from OSDU"
consumes:
- application/json
produces:
- application/json
parameters:
- in: query
name: hmac
type: string
required: true
responses:
'200':
description: OK
...
```
</details>
<details><summary>A simple Java implementation of the endpoint</summary>
```
@POST
@Path(<ConsumerEndpoint>)
public Response processMessage(@NotBlank(message = "Request body can not be null") String data,
@NotBlank(message = "'hmac signature' can not be null or empty") @QueryParam("hmac") String hmac,
The notification service expects a response with the code in the 200-299 range for successfully acknowledged messages. It expects such a response from the consumer endpoint within 30 seconds. If acknowledgement is not received in this time, the notification service will continue to call the endpoint for 5 days. The frequency of the message slows down if it consistently fails to receive a successful acknowledgement.
[Back to Table of Contents](#TOC)
## Update secret for a Subscription <a name="update-subscription"></a>
Consumers might want to regularly update their secret for the Subscriptions to avoid security issues.
This can be done using the DE Notification update subscription API. Consumers must update the "GET" endpoint first to point to new secret, as the same verification will be performed again with new secret value.
