7.3.1. Notification

Get the OpenAPI file for this interface: notification.yaml

Notification Services

7.3.1.1. Services

7.3.1.1.1. Subscriber

POST /v1/subscriptions

Subscribe to a topic

Subscribes a client to receive event notification.

Subscriptions are idempotent. Subscribing twice for the same topic and endpoint (protocol, address) will return the same subscription ID and the subscriber will receive only once the notifications.

Scope required: notif.sub.write

Query Parameters:
 
  • topic (string) – The name of the topic for which notifications will be sent (Required)
  • protocol (string) – The protocol used to send the notification
  • address (string) – the endpoint address, where the notifications will be sent. (Required)
  • policy (string) –

    The delivery policy, expressing what happens when the message cannot be delivered.

    If not specified, retry will be done every hour for 7 days.

    The value is a set of integer separated by comma:

    • countdown: the number of seconds to wait before retrying. Default: 3600.
    • max: the maximum max number of retry. -1 indicates infinite retry. Default: 168
Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "uuid": "string",
    "topic": "string",
    "protocol": "http",
    "address": "string",
    "policy": "string",
    "active": true
}

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}

Callback: onEvent

POST {$request.query.address}
Status Codes:
Request Headers:
 
  • message-type – the type of the message (Required)
  • subscription-id – the unique ID of the subscription
  • message-id – the unique ID of the message (Required)
  • topic-id – the unique ID of the topic (Required)

Example request:

POST {$request.query.address} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "type": "SubscriptionConfirmation",
    "token": "string",
    "topic": "string",
    "message": "string",
    "messageId": "string",
    "subject": "string",
    "subscribeURL": "https://example.com",
    "timestamp": "string"
}

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
GET /v1/subscriptions

Get all subscriptions

Scope required: notif.sub.read

Status Codes:

Example request:

GET /v1/subscriptions HTTP/1.1
Host: example.com
Authorization: Bearer cn389ncoiwuencr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "uuid": "string",
        "topic": "string",
        "protocol": "http",
        "address": "string",
        "policy": "string",
        "active": true
    }
]

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
DELETE /v1/subscriptions/{uuid}

Unsubscribe from a topic

Unsubscribes a client from receiving notifications for a topic

Scope required: notif.sub.write

Parameters:
  • uuid (string) – the unique ID returned when the subscription was done
Status Codes:

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
GET /v1/subscriptions/confirm

Confirm the subscription

Confirm a subscription

Scope required: notif.sub.write

Query Parameters:
 
  • token (string) – the token sent to the endpoint (Required)
Status Codes:

Example request:

GET /v1/subscriptions/confirm?token=string HTTP/1.1
Host: example.com
Authorization: Bearer cn389ncoiwuencr

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}

7.3.1.1.2. Publisher

POST /v1/topics

Create a topic

Create a new topic. This service is idempotent.

Scope required: notif.topic.write

Query Parameters:
 
  • name (string) – The topic name (Required)
Status Codes:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "uuid": "string",
    "name": "string"
}

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
GET /v1/topics

Get all topics

Scope required: notif.topic.read

Status Codes:

Example request:

GET /v1/topics HTTP/1.1
Host: example.com
Authorization: Bearer cn389ncoiwuencr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "uuid": "string",
        "name": "string"
    }
]

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
DELETE /v1/topics/{uuid}

Delete a topic

Delete a topic

Scope required: notif.topic.write

Parameters:
  • uuid (string) – the unique ID returned when the topic was created
Status Codes:

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
POST /v1/topics/{uuid}/publish

Post a notification to a topic.

Scope required: notif.topic.publish

Parameters:
  • uuid (string) – the unique ID of the topic
Query Parameters:
 
  • subject (string) – the subject of the message.
Status Codes:

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}

7.3.1.2. Notification Message

This section describes the messages exchanged through notification. All messages are encoded in json. They are generated by the emitter (the source of the event) and received by zero, one, or many receivers that have subscribed to the type of event.

Table 7.1 Event Type & Message
Event Type Message
liveBirth
  • source: identification of the system emitting the event
  • uin of the new born
  • uin1 of the first parent (optional if parent is unknown)
  • uin2 of the second parent (optional if parent is unknown)

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "uin1": "123456789",
    "uin2": "234567890"
}
death
  • source: identification of the system emitting the event
  • uin of the dead person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
birthCancellation
  • source: identification of the system emitting the event
  • uin of the person whose birth declaration is being cancelled

Example:

{
    "source": "systemX",
    "uin": "123456789",
}
foetalDeath
  • source: identification of the system emitting the event
  • uin of the new born

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
marriage
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
divorce
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
annulment
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
separation
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
adoption
  • source: identification of the system emitting the event
  • uin of the child
  • uin1 of the first parent
  • uin2 of the second parent (optional)

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "uin1": "234567890"
}
legitimation
  • source: identification of the system emitting the event
  • uin of the child
  • uin1 of the first parent
  • uin2 of the second parent (optional)

Example:

{
    "source": "systemX",
    "uin": "987654321",
    "uin1": "123456789",
    "uin2": "234567890"
}
recognition
  • source: identification of the system emitting the event
  • uin of the child
  • uin1 of the first parent
  • uin2 of the second parent (optional)

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "uin2": "234567890"
}
changeOfName
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
changeOfGender
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
updatePerson
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
newPerson
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
duplicatePerson
  • source: identification of the system emitting the event
  • uin of the person to be kept
  • duplicates: list of uin for records identified as duplicates

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "duplicates": [
        "234567890",
        "345678901"
    ]
}

Note

Anonymized notification of events will be treated separately.