7.1. Notification¶

This is version 1.2.0 of this interface.

7.1.1. Services¶

7.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. Constraints: possible values are http, email.
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

200 OK – Subscription successfully created. Waiting for confirmation message.
400 Bad Request – Bad request.
500 Internal Server Error – Unexpected error.

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 400 Bad Request
Content-Type: application/json

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

Example response:

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

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

Callback: onEvent

POST {$request.query.address}¶

Form Parameters

body – The message.

Request Headers

message-type – the type of the message. Constraints: possible values are SubscriptionConfirmation, Notification. (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)

Status Codes

200 OK – Message received and processed.
500 Internal Server Error – Unexpected error.

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": "2022-12-16T14:49:45.696550"
}

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

200 OK – Get all subscriptions.
500 Internal Server Error – Unexpected error.

Example request:

GET /v1/subscriptions HTTP/1.1
Host: example.com

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

204 No Content – Subscription successfully removed.
400 Bad Request – Bad request.
404 Not Found – Subscription not found.
500 Internal Server Error – Unexpected error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

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

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

200 OK – Subscription successfully confirmed.
400 Bad Request – Bad request (invalid token).
500 Internal Server Error – Unexpected error.

Example request:

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

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

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

Example response:

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

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

7.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

200 OK – Topic was created.
400 Bad Request – Bad request.
500 Internal Server Error – Unexpected error.

Example response:

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

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

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "code": 1,
    "message": "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

200 OK – Get all topics.
500 Internal Server Error – Unexpected error.

Example request:

GET /v1/topics HTTP/1.1
Host: example.com

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

204 No Content – Topic successfully removed.
400 Bad Request – Bad request.
404 Not Found – Topic not found.
500 Internal Server Error – Unexpected error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

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

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.

Form Parameters

body – Message posted.

Status Codes

200 OK – Notification published.
400 Bad Request – Bad request.
500 Internal Server Error – Unexpected error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

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

Example response:

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

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

7.1.1.3. Receiver¶

POST notify_URL¶

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)

Status Codes

200 OK – Message received and processed.
500 Internal Server Error – Unexpected error

Example request (Subscription Confirmation):

POST notify_URL HTTP/1.1
Host: example.com
Content-Type: application/json
Message-Type: SubscriptionConfirmation
Subscription-Id: XXX
Message-Id: YYY
Topic-ID: ZZZ

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

Example request (Event):

POST notify_URL HTTP/1.1
Host: example.com
Content-Type: application/json
Message-Type: Notification
Message-Id: YYY
Topic-ID: ZZZ

{"key": "data"}

Example response:

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

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

7.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.

7.1. Notification¶

7.1.1. Services¶

7.1.1.1. Subscriber¶

7.1.1.2. Publisher¶

7.1.1.3. Receiver¶

7.1.2. Notification Message¶

Navigation

Related Topics