Introduction

Endpoint

...

Action name

...

get token

...

HTTP path

...

To inform partners about events transpiring on the Platform, the Thinksurance Public API V2, hereafter referred to as "the API," features a notification system. This system issues notifications in a form of webhooks to all relevant stakeholders through HTTP requests. The API transmits minimal payloads within the HTTP body, informing partners about entities affected by the event. These payloads exclusively consist of references to entities, comprising their unique identifiers and links to the API, allowing partners to access comprehensive information about them. This design aims to streamline the validation process for notification payloads on the partners' end, offering a more generalised approach suitable for a wide range of entities and events.

Webhook

Notification of an event is carried out through a webhook, dispatched in the form of a POST HTTP request from the API to a designated endpoint chosen by the partner. This endpoint adheres to a uniform JSON payload structure across all events and entities. Successful execution of a notification webhook necessitates the partner's system to respond with a 204 HTTP status code. Error responses are structured as described below. In the event of an error response from the partner's system, the webhook will be retried, with a maximum of three attempts. Following the conclusive failed retry, it is anticipated that the Thinksurance Support team will contact the partner to elucidate the issue.

Attributes of the HTTP request

...

hash

...

string

...

required

...

A security-sensitive value provided by Thinksurance Support Team.

...

secret

...

string

...

required

...

A security-sensitive value provided by Thinksurance Support Team.

Attributes of the HTTP response

...

Success response

...

token

...

string

...

required

...

A security token required for future API usage.

...

expired

...

string

...

required

...

Date and time when the security token expires.
MySQL format for datetime: {{ YYYY-MM-DD hh:mm:ss }}

...

Failed response

...

error

...

string

...

required

...

It contains a reason for the failed request.

Examples

...

eventType	string	required	An actual business event that happened on the Platform. It is a string enumeration and it must have one of following values: InquiryCreated InquiryUpdated InquiryProposalCreated InquiryOrdered
eventTime	string	required	Exact time the business event occurred on the Microservice, formatted according to RFC-3339.
eventId	string	required	A unique identifier of the event on the Platform. Consumers might use it for internal tracking purposes.
notificationId	string	required	A unique identifier for the sent notification
accountReference	string	required	An unique identifier of account (in this case, account tag from Thinksurance System) for which business event occurred.
brokerReference	string	required	An unique identifier of broker (in this case, original broker identifier from the partner system) for which business event occurred.
affected	array	required	A list of references to data that is affected by the occurred event. Each element of the array is one of the Affected Scheme.
Affected Scheme
referenceType	string	required	The type of the reference, bound to the underlying entity that was affected by the event. One event can refer to multiple different affected entities. The referenceType can have one of the following potential values: inquiry, consultation, customer, booking, contract, file, offer, questionnaire, tender.
referenceId	string	required	A unique identifier referencing the underlying entity. The value is an opaque string with a maximum length of 64 ASCII characters. Its value should not be interpreted by clients in any way.
links	array	optional	It contains a list of all endpoints from where the data on a particular entity can be fetched. Data can be in the form of a REST API response containing entity information, binary data representing a file or any plain text format containing some more information on the entity. The response always contains data that was relevant for that entity at the time the particular event occurred. The resource will always either return a HTTP success (2xx), redirect (3xx), or error (4xx) codes. Clients are expected to correctly interpret redirections. In some cases, for particular reference type and event type (like in case of deletion), links parameter might be empty. Each element of the array is one of the Link Scheme.
Link Scheme
contentType	string	required	Defines the content of the response from the endpoint as a MIME type used in the HTTP Content-Type header. Possible values: for REST API: application/json, application/xml for files: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, image/jpeg, image/png for publicly available content: text/html, text/plain
href	string	required	An absolute path for a snapshot of the resource relevant to the event itself. Each payload in the REST API is cached and it doesn’t change over time (snapshots of data), even if the structure of the underlying entities changes. That means, that the response for the same reference type might vary, depending on the time the event occurred and therefore when the snapshot was created.

Expected HTTP response from the Partner’s system

Examples

As previously stated the Notification System dispatch a POST HTTP request to the Partner’s endpoint, which previously must be given to the Thinksurance Support team, so integration can be established. Below, instances of potential communication between the API and consumers are provided.

# HTTP POST
#
/api/token
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "eventType": "inquiry_created",
  "eventTime": "2020-12-09T16:09:53+00:00",
  "eventId": "66948656-d8cd-452f-a9c5-000eca2d0684",
  "notificationId": "ded21bfa-18cb-11ef-9fc4-0a5332324815",
  "accountReference": "demopool",
  "brokerReference": "456",
  "translations": {
    "eventType": {
      "de_DE": "Beratung erstellt"
    }
  },
  "affected": [
    {
      "hashreferenceType": "some long string value",
  "secret": "some string value"
}

"inquiry",
      "referenceId": "567",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://app.thinksurance.de/ipn/inquiry/567"
        }
      ]
    }
  ]
}

# HTTP 200POST
status code
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "token": "some long string value",
  "expired": "2024-01-26 14:54:46"
}
  "eventType": "InquiryOrdered",
  "eventTime": "2024-04-26T16:48:31.118Z",
  "eventId": "",
  "notificationId": "ded21bfa-18cb-11ef-9fc4-0a5332324815",
  "translations": {
    "eventType": {
      "de_DE": "Deckungsauftrag erstellt"
    }
  },
  "accountReference": "thinksurance",
  "brokerReference": "420",
  "affected": [
    {
      "referenceType": "inquiry",
      "referenceId": "2144385",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://ipn.thinksurance.de/api/ipn/inquiry/2144385"
        }
      ]
    },
    {
      "referenceType": "contract",
      "referenceId": "b75fcf90-0584-4bd8-850e-91eb0e4c15e1",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://rest.thinksurance.de/api/public/v2/notifications/47/contracts/b75fcf90-0584-4bd8-850e-91eb0e4c15e1"
        }
      ]
    },
    {
      "referenceType": "customer",
      "referenceId": "695056",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://rest.thinksurance.de/api/public/v2/notifications/47/customers/695056"
        }
      ]
    }
  ]
}

# HTTP 204 status code

# HTTP 200400 status code
# 'Content-Type': 'application/json'
{
  "errorerrors": [
"API User    "Unknown entity tender.",
    "Attribute 'referenceId' is notof existingthe orwrong deactivatedtype."
  ]
}

Sequence diagram

Whenever some event occurs on the Thinksurance Platform, Notification System will notify Partner’s System via a webhook. After receiving a notification, the Partner’s system can get information about involved entities by sending HTTP requests to the API.

Recommendation and expectation from Thinksurance side is that the Partner asynchronously fetch data about affected entities from the API, independent fro the original webhook HTTP request. That practically means that after a webhook, the partner is encouraged to store notification payload in some kind of internal storage and return 204 HTTP response.
After that, in a separate thread, the partner system should retrieve data bound to entities on the API.