Versions Compared

Old Version 4

changes.mady.by.user Marko Milojevic

Saved on

compared with

New Version Current

changes.mady.by.user Timm Weitzel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Introduction

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.

Action name

send notification

HTTP path

Defined from partner side, the Thinksurance Support team should get information on partner’s endpoint built to receive a HTTP request, holding notification’s payload.

HTTP method

POST

Attributes of the HTTP request

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:

  • for inquiry: inquiry_created, inquiry_updated, inquiry_cancelled

  • for tender: tender_created, tender_closed, tender_cancelled

  • for offer: offers_created, offer_selected

  • for booking: booking_created, proposal_created, contract_createdInquiryCreated

  • 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

Success response

HTTP status code 204

Failed response

HTTP status code 400

errors

array

required

A list of strings containing all errors found on 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 Request with inquiry_created event

Code Block
languagejson
# HTTP POST
# '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": [
    {
      "referenceType": "inquiry",
      "referenceId": "567",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://app.thinksurance.de/ipn/inquiry/567"
        },
      ]
 {   }
  ]
}

HTTP Request with inquiry_orderd event

Code Block
languagejson
# HTTP POST
 "contentType": "plain/html",
       # 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "eventType": "InquiryOrdered",
  "hrefeventTime": "https://demopool.thinksurance.de/inquiry/32efda3424432"
        }
      ]
    },
    {
      "referenceType2024-04-26T16:48:31.118Z",
  "eventId": "customer",

     "referenceIdnotificationId": "789ded21bfa-18cb-11ef-9fc4-0a5332324815",
      "linkstranslations": [
        {
 
        "contentTypeeventType": "application/xml",{
          "href"de_DE": "https://app.thinksurance.de/ipn/customer/789"
 Deckungsauftrag erstellt"
      }
     
]     },
    {
      "referenceType"accountReference": "filethinksurance",
   
  "referenceIdbrokerReference": "111420",
 
    "linksaffected": [

       {
          "contentTypereferenceType": "application/jsoninquiry",
          "hrefreferenceId": "https://app.thinksurance.de/api/v1/files/111"2144385",
      "links": [
},         {
          "contentType": "application/pdfjson",
          "href": "https://appipn.thinksurance.de/api/v1ipn/filesinquiry/111/download2144385"
        }
      ]
    },
  ] }

HTTP Request with tender_cancelled event

Code Block
languagejson
# HTTP POST
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "eventType {
      "referenceType": "tender_cancelledcontract",
  "eventTime": "2020-12-09T16:09:53+00:00",   "eventIdreferenceId": "66948656b75fcf90-d8cd0584-452f4bd8-a9c5850e-000eca2d068491eb0e4c15e1",
  "accountReference": "demopool",   "brokerReferencelinks": "456", [
     "translations": {  {
  "eventType": {       "de_DEcontentType": "Ausschreibung abgebrochen"application/json",
    }   },   "affectedhref": ["https://rest.thinksurance.de/api/public/v2/notifications/47/contracts/b75fcf90-0584-4bd8-850e-91eb0e4c15e1"
    {    }
  "referenceType": "tender",       "referenceId": "111"]
    },
    {
      "referenceType": "inquirycustomer",
      "referenceId": "567695056",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://apprest.thinksurance.de/ipnapi/inquiry/567"
        },
        {
          "contentType": "plain/html",
          "href": "https://demopool.thinksurance.de/inquiry/32efda3424432public/v2/notifications/47/customers/695056"
        }
      ]
    }
  ]
}

Successful HTTP Response

Code Block
languagejson
# HTTP 204 status code

Failed HTTP Response

Code Block
languagejson
# HTTP 400 status code
# 'Content-Type': 'application/json'
{
  "errors": [
    "Unknown entity tender.",
    "Attribute 'referenceId' is of the wrong type."
  ]
}

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.

...