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

Affected Scheme
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_created
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.
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.
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

# 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",
  "affected": [
    {
      "referenceType": "inquiry",
      "referenceId": "567",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://app.thinksurance.de/ipn/inquiry/567"
        },
        {
          "contentType": "plain/html",
          "href": "https://demopool.thinksurance.de/inquiry/32efda3424432"
        }
      ]
    },
    {
      "referenceType": "customer",
      "referenceId": "789",
      "links": [
        {
          "contentType": "application/xml",
          "href": "https://app.thinksurance.de/ipn/customer/789"
        }
      ]
    },
    {
      "referenceType": "file",
      "referenceId": "111",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://app.thinksurance.de/api/v1/files/111"
        },
        {
          "contentType": "application/pdf",
          "href": "https://app.thinksurance.de/api/v1/files/111/download"
        }
      ]
    }
  ]
}

HTTP Request with tender_cancelled event

# HTTP POST
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "eventType": "tender_cancelled",
  "eventTime": "2020-12-09T16:09:53+00:00",
  "eventId": "66948656-d8cd-452f-a9c5-000eca2d0684",
  "affected": [
    {
      "referenceType": "tender",
      "referenceId": "111"
    },
    {
      "referenceType": "inquiry",
      "referenceId": "567",
      "links": [
        {
          "contentType": "application/json",
          "href": "https://app.thinksurance.de/ipn/inquiry/567"
        },
        {
          "contentType": "plain/html",
          "href": "https://demopool.thinksurance.de/inquiry/32efda3424432"
        }
      ]
    }
  ]
}

Successful HTTP Response

# HTTP 204 status code

Failed HTTP Response

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

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.