KYB Webhooks

Requirements

• Setting up webhooks requires Admin role
• Setup webhooks
• A valid SSL certificate is required on your endpoint for TLS webhooks to prevent delivery failures.

Setting up notifications

To set up notifications, log in to your dashboard and navigate to Settings -> Notifications.

---

Webhook events for Companies

COMPANY SUBMIT

Company submit Webhook

This notification is sent when company information is submitted.

Find info about webhook signing here.

header Parameters

Idenfy-Event-Type required	string Value: "COMPANY_SUBMIT"
Idenfy-Signature	string Webhook signature

Request Body schema: application/json

required

id required	string
submissionTime	string or null <date-time> Date and time when KYB form submit endpoint was called.
soleProprietor	boolean
clientId required	string <= 100 characters A unique string identifying a client on your side.
externalRef	string or null <= 40 characters Any additional value chosen by you.

Responses

Request samples

• Payload

Content type

application/json

{

• "id": "string",
• "submissionTime": "2019-08-24T14:15:22Z",
• "soleProprietor": true,
• "clientId": "string",
• "externalRef": "string"

}

COMPANY REVIEW

Company review Webhook

This notification is sent when a company verification is completed.

Find info about webhook signing here.

header Parameters

Idenfy-Event-Type required	string Value: "COMPANY_REVIEW"
Idenfy-Signature	string Webhook signature

Request Body schema: application/json

required

id required	string
companyName required	string <= 255 characters
registrationNumber	string or null <= 100 characters
	(ApprovalStatusEnum (string or null)) or (NullEnum (any or null)) Review approval status.
denyReason	string or null <= 64 characters The reason why this KYB form was denied.
required	object or null
soleProprietor	boolean
amlComment	string or null
sanctionsCheckStatus	string (AmlCheckStatusEnum) Enum: "NOT_CHECKED" "NO_FLAGS" "FLAGS_FOUND" "TRUE_POSITIVE" "FALSE_POSITIVE"
required	object (ManagerAccountOld)
sanctionsStatusSetAt	string or null <date-time>
required	object or null
required	Array of objects (BeneficiaryWebhook)
required	Array of objects
negativeNewsComment	string or null
negativeNewsStatus	string (AmlCheckStatusEnum) Enum: "NOT_CHECKED" "NO_FLAGS" "FLAGS_FOUND" "TRUE_POSITIVE" "FALSE_POSITIVE"
required	object (ManagerAccountOld)
newsStatusSetAt	string or null <date-time>
required	Array of objects
clientId required	string <= 100 characters A unique string identifying a client on your side.
externalRef	string or null <= 40 characters Any additional value chosen by you.
relatedClientScanRefs	Array of strings or null (Scan refs) [ items <= 40 characters ^[^,]+$ ]

Responses

Request samples

• Payload

Content type

application/json

{

• "id": "string",
• "companyName": "string",
• "registrationNumber": "string",
• "approvalStatus": "APPROVED",
• "denyReason": "string",
• "statusChangedBy": {

  • "id": 0,
  • "username": "string",
  • "email": "user@example.com",
  • "name": "string",
  • "surname": "string"

  },
• "soleProprietor": true,
• "amlComment": "string",
• "sanctionsCheckStatus": "NOT_CHECKED",
• "sanctionsStatusSetBy": {

  • "id": 0,
  • "username": "string",
  • "email": "user@example.com",
  • "name": "string",
  • "surname": "string"

  },
• "sanctionsStatusSetAt": "2019-08-24T14:15:22Z",
• "companyCheck": {

  • "property1": null,
  • "property2": null

  },
• "beneficiaries": [

  • {

    • "id": "string",
    • "amlComment": "string",
    • "pepsCheckStatus": "NOT_CHECKED",
    • "pepsStatusSetBy": {

      • "id": 0,
      • "username": "string",
      • "email": "user@example.com",
      • "name": "string",
      • "surname": "string"

      },
    • "pepsStatusSetAt": "2019-08-24T14:15:22Z",
    • "sanctionsCheckStatus": "NOT_CHECKED",
    • "sanctionsStatusSetBy": {

      • "id": 0,
      • "username": "string",
      • "email": "user@example.com",
      • "name": "string",
      • "surname": "string"

      },
    • "sanctionsStatusSetAt": "2019-08-24T14:15:22Z",
    • "negativeNewsComment": "string",
    • "negativeNewsStatus": "NOT_CHECKED",
    • "newsStatusSetBy": {

      • "id": 0,
      • "username": "string",
      • "email": "user@example.com",
      • "name": "string",
      • "surname": "string"

      },
    • "newsStatusSetAt": "2019-08-24T14:15:22Z",
    • "beneficiaryCheck": {

      • "property1": null,
      • "property2": null

      },
    • "negativeNewsCheck": {

      • "property1": null,
      • "property2": null

      },
    • "scanRef": {

      • "property1": null,
      • "property2": null

      }

    }

  ],
• "shareholderCheck": [

  • {

    • "property1": null,
    • "property2": null

    }

  ],
• "negativeNewsComment": "string",
• "negativeNewsStatus": "NOT_CHECKED",
• "newsStatusSetBy": {

  • "id": 0,
  • "username": "string",
  • "email": "user@example.com",
  • "name": "string",
  • "surname": "string"

  },
• "newsStatusSetAt": "2019-08-24T14:15:22Z",
• "negativeNewsCheck": [

  • {

    • "property1": null,
    • "property2": null

    }

  ],
• "clientId": "string",
• "externalRef": "string",
• "relatedClientScanRefs": [

  • "string"

  ]

}

COMPANY AML REVIEW

Company aml review Webhook

This notification is sent when an AML review status is manually updated for a company or it's beneficiaries.

Find info about webhook signing here.

header Parameters

Idenfy-Event-Type required	string Value: "COMPANY_AML_REVIEW"
Idenfy-Signature	string Webhook signature

Request Body schema: application/json

required

amlReviewSubjectType required	string (AmlReviewSubjectEnum) Enum: "COMPANY" "BENEFICIARY" "SHAREHOLDER"
id required	string
companyId required	string
clientId	string
externalRef	string or null
negativeNewsComment	string or null
	(AmlCheckStatusEnum (string or null)) or (NullEnum (any or null))
	object or null
newsStatusSetAt	string or null <date-time>
amlComment	string or null
	(AmlCheckStatusEnum (string or null)) or (NullEnum (any or null))
	object or null
pepsStatusSetAt	string or null <date-time>
	(AmlCheckStatusEnum (string or null)) or (NullEnum (any or null))
	object or null
sanctionsStatusSetAt	string or null <date-time>

Responses

Request samples

• Payload

Content type

application/json

{

• "amlReviewSubjectType": "COMPANY",
• "id": "string",
• "companyId": "string",
• "clientId": "string",
• "externalRef": "string",
• "negativeNewsComment": "string",
• "negativeNewsStatus": "NOT_CHECKED",
• "newsStatusSetBy": {

  • "id": 0,
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com"

  },
• "newsStatusSetAt": "2019-08-24T14:15:22Z",
• "amlComment": "string",
• "pepsCheckStatus": "NOT_CHECKED",
• "pepsStatusSetBy": {

  • "id": 0,
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com"

  },
• "pepsStatusSetAt": "2019-08-24T14:15:22Z",
• "sanctionsCheckStatus": "NOT_CHECKED",
• "sanctionsStatusSetBy": {

  • "id": 0,
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com"

  },
• "sanctionsStatusSetAt": "2019-08-24T14:15:22Z"

}

COMPANY EXPIRATION

Company expiration Webhook

This notification is sent when a company verification is nearing expiration or expires.

Find info about webhook signing here.

header Parameters

Idenfy-Event-Type required	string Value: "COMPANY_EXPIRATION"
Idenfy-Signature	string Webhook signature

Request Body schema: application/json

id required	string
	(CompanyExpirationStatusEnum (string or null)) or (BlankEnum (any or null)) or (NullEnum (any or null))

Responses

Request samples

• Payload

Content type

application/json

{

• "id": "string",
• "expirationStatus": "PENDING"

}

COMPANY INFO REQUEST

Company info request Webhook

This notification is sent when additional company info is requested and when the company form token expires.

Find info about webhook signing here.

header Parameters

Idenfy-Event-Type required	string Value: "COMPANY_INFO_REQUEST"
Idenfy-Signature	string Webhook signature

Request Body schema: application/json

required

companyId required	string
token required	string
date required	string <date-time>
email required	string or null <email> <= 254 characters
required	object or null
status required	string (CompanyInfoRequestStatusEnum) Enum: "REQUESTED" "EXPIRED" "CANCELED"

Responses

Request samples

• Payload

Content type

application/json

{

• "companyId": "string",
• "token": "string",
• "date": "2019-08-24T14:15:22Z",
• "email": "user@example.com",
• "manager": {

  • "id": 0,
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com"

  },
• "status": "REQUESTED"

}

COMPANY DELETE

Company delete Webhook

This notification is sent when a company is deleted.

Find info about webhook signing here.

header Parameters

Idenfy-Event-Type required	string Value: "COMPANY_DELETE"
Idenfy-Signature	string Webhook signature

Request Body schema: application/json

required

date required	string <date-time>
required	object or null
companyId required	string

Responses

Request samples

• Payload

Content type

application/json

{

• "date": "2019-08-24T14:15:22Z",
• "manager": {

  • "id": 0,
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com"

  },
• "companyId": "string"

}

---

Webhook events for Reports

GOV ORDERED DOCUMENT

Gov ordered document Webhook

This notification is sent when a gov registers document, which was ordered using the API, is delivered.

Find info about webhook signing here.

header Parameters

Idenfy-Event-Type required	string Value: "GOV_ORDERED_DOCUMENT"
Idenfy-Signature	string Webhook signature

Request Body schema: application/json

required

id required	string <uuid>
title	string or null
documentFormat	string <= 5 characters
productKey required	string
expectedDeliveryTime required	string <date-time>
price required	number <double> >= 0
deliveredAt	string or null <date-time>
status	string (GovDocumentOrderStatusEnum) Enum: "NOT_ORDERED" "IN_PROGRESS" "FINISHED" "FAILED" "TIMED_OUT"
file	string or null <uri>

Responses

Request samples

• Payload

Content type

application/json

{

• "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
• "title": "string",
• "documentFormat": "strin",
• "productKey": "string",
• "expectedDeliveryTime": "2019-08-24T14:15:22Z",
• "price": 0.1,
• "deliveredAt": "2019-08-24T14:15:22Z",
• "status": "NOT_ORDERED",
• "file": "http://example.com"

}

---

Webhook troubleshooting

Ensure that:

• You have provided a valid callback endpoint (it does not contain typos and is a fully specified URL with HTTP schema, port and domain name).
• The provided endpoint can be reached from the internet.
• Your SSL is set up correctly. Our system can only send webhooks to URLs with valid SSL certificates.
• You are truly not receiving a callback and your framework is not accidentally returning some other HTTP response e.g. 422 or 500.

Review webhooks sent via iDenfy dashboard

By going to Settings → Notifications → selecting Recently sent in the top right corner, you can search for specific notifications and see what was sent, and what status we received from your server.

1. Search field where you can use scanRef to search specific notifications for verification.

2. The response we received from your server:

   • 0 - No Response: No communication; server unreachable.
   • 2xx - Success: Request successful, information returned.
   • 3xx - Redirection: Further action needed, request redirected.
   • 4xx - Client Errors: Your servers couldn’t handle the response
   • 5xx - Server Errors: Request valid, there is a problem with the server

3. Date and time when notification was sent

4. Attempt to resend the webhook.

5. Shows full information of what was sent in JSON format.