About the Endpoint Notification Protocol

When a Pending Match Request is resolved, Match can be configured to send a JSON message to a URL endpoint. This allows automatic business processes to be triggered once a Reconciliation Manager reviews and resolves a Pending Match.

(This Notification protocol is not part of the TAP Match API.)

Configuration

(warning) Currently only one Endpoint is supported per Matchgrid.

  1. From the Matchgrid configuration page, select Endpoints, then (plus) Add a New Endpoint.
    1. URL: The exact URL the notification will be sent to
    2. Username: If required, the username to authenticate with (using Basic Authentication).
    3. Password: If required, the password to authenticate with (using Basic Authentication).
  2. From the Matchgrid configuration page, select Matchgrid Settings.
    1. Resolution Notification Endpoint: Select the Endpoint created above.

Message Format (version 1)

JSON Document

The JSON message format is described in this JSON Schema document.

  • sor: The System of Record label, as configured
  • sorid: The System of Record Identifier, as provided in the initial match request
  • requestId: The identifier assigned by Match to the initial match request


Example Notification
{
  "meta": {
    "source": "COmanage Match",
    "event": "match-resolution",
    "format": "1"
  },
  "sor": "hrms",
  "sorid": "A595847",
  "matchRequest": "136",
  "referenceId": "ac22eb2b-37a8-4faa-b427-8b5a399d9fcf",
  "resolutionTime": "2022-08-07T15:00:03Z"
}

Transfer Protocol

The JSON document will be transferred to the exact URL as configured using HTTP POST. The content-type will be set to application/json.

Endpoint Response Codes

Success

Any HTTP Response Code in the 2xx range (>= 200, <= 299) is treated as successfully sent.

Error

Any other HTTP Response Code is treated as an error. On error, the endpoint may return a simple JSON document with an error that will be recorded in the Matchgrid History for the subject SOR/SORID.

Example Error Message
{
  "error": "Something went wrong"
}

There is not currently a mechanism for retrying notifications that were not accepted by the endpoint.

Integration with COmanage Registry

COmanage Registry can be configured to process Endpoint Notifications, as described here.

Changes From Earlier Versions

As of Match v1.1.0

  • Match Resolution Endpoint Notification capability introduced.
  • No labels