Skip to main content

Webhooks

A webhook enables us to push notifications from our system to yours. Make sure the URL of your registered HTTP callbacks are publicly available and that required ports in your firewall are open.

If you're developing on a computer without direct access to the internet, you can use a product such as https://ngrok.com/ to create a public tunnel to a specific port on your computer.

1. Register Webhook​

Note on Security​

By setting a secret when creating the webhook, the requests made by Pliance will have the header X-PLIANCE-SECRET. This can be used to verify that the request was made from Pliance.

danger

Secret will only be sent if the url is using the HTTPS-scheme, to secure privileged information.

Save your webhook​

let request: WebhookUpdateCommand = {
  url: "https://webhook.pliance.io",
  secret: "031356FD-0686-4164-89F9-632882700679",
  enabled: true
};

let response = await client.saveWebhook(request);
Response
{
  "status": "Success",
  "success": true,
  "message": null,
  "checkpoint": "fd362e0faabd9e19de260ae542fc782210c05067118b61d99a327f4d77adbe1b"
}

Test your webhook​

Upon successful registration, Pliance provides a way to post sample data to your application in order to test your webhook.

let request: WebhookPokeQuery = {
  type: WebhookPokeType.PersonSanctionMatched,
};

let response = await client.poke(request);
Response
{
  "remoteBody": null,
  "remoteStatusCode": 0,
  "status": "Error",
  "success": false,
  "message": "Name or service not known (webhook:5399)",
  "checkpoint": "0000000000000000000000000000000000000000000000000000000000000000"
}

2. Webhook Data Payload​

This section aims to describe the schema of the JSON that is posted to your webhook URL when events are triggered.

Person​

When a new match is added​

{
    "type": "PersonSanctionMatched",
    "checkpoint": "dccf2e3d55b6c61f9146e9c439643da6ca810cf49a36df3caad67327242a22b8",
    "metadata": {
        "subject": "1",
        "ip": "api",
        "givenName": "Tomas",
        "timestampUtc": "2021-02-01T11:56:37.3326642Z"
    },
    "body": {
        "aliasId": "8f63040454e4943574defb78b154626d2003905a5671d12dd161b55d5d2da139",
        "matchId": "31aabce004c79b0ee8c3e1f071f335b9",
        "personReferenceId": "10192",
        "matchedFirstName": [{
            "text": "Sven",
            "isMatch": true
        }, {
            "text": " ",
            "isMatch": false
        }, {
            "text": "Olof",
            "isMatch": true
        }, {
            "text": " ",
            "isMatch": false
        }, {
            "text": "Joachim",
            "isMatch": true
        }],
        "matchedLastName": [{
            "text": "Palme",
            "isMatch": true
        }],
        "isPep": true,
        "isRca": false,
        "isSanction": true,
        "firstName": "Sven Olof Joachim",
        "lastName": "Palme"
    }
}

When a new match is removed​

{
    "type": "PersonSanctionMatchRemoved",
    "checkpoint": "feddbd93682ac8ead4a2d3447b234aa52441e86feb0d54b31a9da3353a5b0ef9",
    "metadata": {
        "subject": "1",
        "ip": "api",
        "givenName": "Tomas",
        "timestampUtc": "2021-02-01T12:05:43.7376753Z"
    },
    "body": {
        "personReferenceId": "10192",
        "aliasId": "8f63040454e4943574defb78b154626d2003905a5671d12dd161b55d5d2da139",
        "classification": "Unknown",
        "matchId": "31aabce004c79b0ee8c3e1f071f335b9"
    }
}

Company​

When a new match is added​

{
    "type": "CompanySanctionMatched",
    "checkpoint": "dccf2e3d55b6c61f9146e9c439643da6ca810cf49a36df3caad67327242a22b8",
    "metadata": {
        "subject": "1",
        "ip": "api",
        "givenName": "Tomas",
        "timestampUtc": "2021-02-01T11:56:37.3326642Z"
    },
    "body": {
        "aliasId": "8f63040454e4943574defb78b154626d2003905a5671d12dd161b55d5d2da139",
        "matchId": "31aabce004c79b0ee8c3e1f071f335b9",
        "CompanyReferenceId": "10192",
        "matchedName": [
            {
              "text": "Korea",
              "isMatch": true
            },
            {
              "text": " ",
              "isMatch": false
            },
            {
              "text": "Daesong",
              "isMatch": true
            },
            {
              "text": " ",
              "isMatch": false
            },
            {
              "text": "Bank",
              "isMatch": true
            }
          ],
        "isSanction": true,
        "name": "Korea Daesong Bank"
    }
}

When a new match is removed​

{
    "type": "CompanySanctionMatchRemoved",
    "checkpoint": "feddbd93682ac8ead4a2d3447b234aa52441e86feb0d54b31a9da3353a5b0ef9",
    "metadata": {
        "subject": "1",
        "ip": "api",
        "givenName": "Tomas",
        "timestampUtc": "2021-02-01T12:05:43.7376753Z"
    },
    "body": {
        "CompanyReferenceId": "10192",
        "aliasId": "8f63040454e4943574defb78b154626d2003905a5671d12dd161b55d5d2da139",
        "classification": "Unknown",
        "matchId": "31aabce004c79b0ee8c3e1f071f335b9"
    }
}

3. Query Webhook​

You can check the status of your registered webhooks by submitting the following query at any time.

let request: WebhookQuery {
};

let response = await client.getWebhook(request);
Response
{
  "data": {
    "enabled": true,
    "url": "https://webhook.pliance.io",
    "secret": "031356FD-0686-4164-89F9-632882700679"
  },
  "status": "Success",
  "success": true,
  "message": null,
  "checkpoint": "0000000000000000000000000000000000000000000000000000000000000000"
}

4. Update Webhook​

Webhook details such as URL and Secret can be updated with the same method you used to register it.

let request: WebhookUpdateCommand = {
  url: "https://webhook.pliance.io",
  secret: "031356FD-0686-4164-89F9-632882700679",
  enabled: true
};

let response = await client.saveWebhook(request);
Response
{
  "status": "Success",
  "success": true,
  "message": null,
  "checkpoint": "fd362e0faabd9e19de260ae542fc782210c05067118b61d99a327f4d77adbe1b"
}

5. Disable Webhook​

Webhooks can be disabled when you no longer wish to receive notifications.

let request: new WebhookUpdateCommand {
  url: "https://webhook.pliance.io",
  secret: "031356FD-0686-4164-89F9-632882700679",
  enabled: false
};

let response = await client.saveWebhook(request);
Response
{
  "status": "Success",
  "success": true,
  "message": null,
  "checkpoint": "fd362e0faabd9e19de260ae542fc782210c05067118b61d99a327f4d77adbe1b"
}

6. Webhook Delivery Status​

Potential delivery failures on your webhooks can be retrieved with the following query.

let request = new WebhookDeliveryFailuresQuery();

let response = await client.listWebhookDeliveryFailures(request);
Response
{
  "status": "Success",
  "success": true,
  "message": null,
  "checkpoint": "fd362e0faabd9e19de260ae542fc782210c05067118b61d99a327f4d77adbe1b",
  "data": {
    "items": [
      {
        "timestamp": "2019-08-24T14:15:22Z",
        "referenceId": "person-1",
        "type": "PersonSanctionMatched",
        "id": "string",
        "reason": "string"
      }
    ]
  }
}