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 required ports opened in your firewall.

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 the secret when creating the webhook all request 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 your 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"
}