> ## Documentation Index > Fetch the complete documentation index at: https://docs.godiligent.ai/llms.txt > Use this file to discover all available pages before exploring further. # Perform CDD > Perform Customer Due Diligence checks ## OpenAPI ````yaml POST /cdds openapi: 3.0.1 info: version: 1.5.0 title: Diligent description: > Download Postman collection [here](https://docs.godiligent.ai/files/postman_collection.json). servers: - url: https://api.godiligent.ai description: Production - url: https://api.sandbox.godiligent.ai description: Sandbox security: - xApiKey: [] tags: - name: CDD description: Customer Due Diligence - name: Company description: Company Information - name: Blocked Companies description: Manage blocked companies - name: Monitorings description: Website monitoring and alerts for changes and risks - name: Webhooks description: > ## How to Secure Webhook Deliveries To ensure that webhook payloads are securely transmitted and verified. This guide explains how to configure and validate webhook deliveries using a shared secret. ### How It Works When setting up a webhook, a secret is configured on both the sender (our system) and the receiver (your endpoint). Each webhook payload is signed using this secret, allowing the receiver to verify its authenticity. #### Step 1: Configuring Your Webhook Secret 1. When creating a webhook in our system, specify a unique secret key. This secret should be a strong, randomly generated string. 2. Store this secret securely on your server; it should never be exposed publicly. #### Step 2: Receiving Webhook Payloads When your server receives a webhook event, the request will include an `X-Signature` header containing a HMAC signature of the payload. Example header: ``` X-Signature: sha256=abcdef1234567890... ``` #### Step 3: Validating the Webhook Signature To verify the webhook payload: 1. Retrieve the `X-Signature` value from the request headers. 2. Compute the HMAC SHA-256 signature of the request payload using your webhook secret. 3. Compare the computed signature with the one in the `X-Signature` header. 4. If they match, the webhook is valid. #### (Python) ```python import hashlib import hmac import json def verify_webhook_signature(secret, payload, signature): computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() expected_signature = f"sha256={computed_signature}" return hmac.compare_digest(expected_signature, signature) # Example usage: secret = "your_webhook_secret" payload = json.dumps({"event": "example"}) received_signature = "sha256=abcdef1234567890..." if verify_webhook_signature(secret, payload, received_signature): print("Valid webhook received!") else: print("Invalid webhook signature!") ``` #### (JavaScript) ```javascript const crypto = require('crypto'); function verifyWebhookSignature (secret, payload, signature) { const computedSignature = `sha256=${crypto.createHmac('sha256', secret) .update(payload) .digest('hex')}`; return crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(signature)); } // Example usage: const secret = "your_webhook_secret"; const payload = JSON.stringify({ event: "example" }); const receivedSignature = "sha256=abcdef1234567890..."; if (verifyWebhookSignature(secret, payload, receivedSignature)) { console.log("Valid webhook received!"); } else { console.log("Invalid webhook signature!"); } ``` #### Security Considerations - Always use HTTPS to prevent interception of webhook payloads. - Reject webhook requests that fail signature validation. - Rotate secrets periodically to enhance security. By following this guide, you ensure that webhook deliveries are secure and trusted. - name: Instant Screening (experimental) description: Instant Website Screening API - name: Name Screening description: Name screening search, alert management and remediation paths: /cdds: post: tags: - CDD summary: Perform CDD description: >- Perform CDD on a given business. Supports idempotency to prevent duplicate processing of the same request. parameters: - name: idempotency-key in: header required: false schema: type: string description: >- Optional idempotency key to ensure the same request is not processed multiple times. If the same key is sent with a different payload, a 409 Conflict error is returned. The result is cached for 7 days. requestBody: content: application/json: schema: $ref: '#/components/schemas/CDDRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CDDResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized '403': description: Forbidden '404': description: Not found '409': description: Conflict - Idempotency key already used with different payload content: application/json: schema: type: object properties: error: type: string example: >- Conflict: Idempotency key already used with different payload '500': description: Internal Server Error security: - xApiKey: [] components: schemas: CDDRequest: type: object oneOf: - $ref: '#/components/schemas/CDDRequestWebsite' - $ref: '#/components/schemas/CDDRequestLegalNameAddress' - $ref: '#/components/schemas/CDDRequestRegisterNumberAndCountryCode' CDDResponse: type: object properties: id: type: string description: The id of the CDD request example: a91a8416-0a38-49e5-887e-8437519b3e78 state: type: string description: The state of the CDD process enum: - INITIATED - IN_PROGRESS - RUNNING_CHECKS - COMPLETED - INCONCLUSIVE - FAILED example: INITIATED input: $ref: '#/components/schemas/CDDInput' created_at: type: string example: '2024-03-20T15:18:36.803Z' format: ISO8601 updated_at: type: string example: '2024-03-20T15:20:12.456Z' format: ISO8601 ValidationError: type: object properties: errors: type: array items: $ref: '#/components/schemas/ValidationErrorItem' required: - errors CDDRequestWebsite: type: object required: - website properties: website: type: string description: The website of the business example: example.com email: type: string description: The email of the business example: fulan@domain.com legal_name: type: string description: The legal name of the business example: PayLane Sp. z o.o. address: type: string description: The address of the business example: Am Generalshof 12, 10117 Berlin, Germany external_id: type: string description: Reference to be used in the customer's system example: 1538c2f9-ff0f-489e-0099-a5f116a4af07 vat_number: type: string description: The VAT number of the business example: BE09999999XX. register_number: type: string description: >- The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported) example: '12345678' country_code: type: string description: Country code in ISO 3166-1 alpha-2 format example: DE description: type: string description: The description of the business example: Software consultancy registry_profile: type: string enum: - FULL - BASIC contact_person: $ref: '#/components/schemas/ContactPerson' risk_check_set_id: type: string description: >- The risk check set id, if not set the default risk check set will be used example: 550e8400-e29b-41d4-a716-446655440000 pull_registry_documents: type: boolean description: >- Whether to pull registry documents for the company (Only supported for DE, and IT) default: false example: true trading_name: type: string description: The trading name (DBA) of the business nullable: true example: Acme Trading Co trading_address: type: string description: The trading address of the business nullable: true example: 123 Trade Street, London CDDRequestLegalNameAddress: type: object required: - legal_name - address properties: website: type: string description: The website of the business example: example.com email: type: string description: The email of the business example: fulan@domain.com legal_name: type: string description: The legal name of the business example: PayLane Sp. z o.o. address: type: string description: The address of the business example: Am Generalshof 12, 10117 Berlin, Germany external_id: type: string description: Reference to be used in the customer's system example: 1538c2f9-ff0f-489e-0099-a5f116a4af07 vat_number: type: string description: The VAT number of the business example: BE09999999XX. register_number: type: string description: >- The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported) example: '12345678' country_code: type: string description: Country code in ISO 3166-1 alpha-2 format example: DE description: type: string description: The description of the business example: Software consultancy registry_profile: type: string enum: - FULL - BASIC contact_person: $ref: '#/components/schemas/ContactPerson' risk_check_set_id: type: string description: >- The risk check set id, if not set the default risk check set will be used example: 550e8400-e29b-41d4-a716-446655440000 pull_registry_documents: type: boolean description: >- Whether to pull registry documents for the company (Only supported for DE, and IT) default: false example: true trading_name: type: string description: The trading name (DBA) of the business nullable: true example: Acme Trading Co trading_address: type: string description: The trading address of the business nullable: true example: 123 Trade Street, London CDDRequestRegisterNumberAndCountryCode: type: object required: - register_number - country_code properties: website: type: string description: The website of the business example: example.com email: type: string description: The email of the business example: fulan@domain.com legal_name: type: string description: The legal name of the business example: PayLane Sp. z o.o. address: type: string description: The address of the business example: Am Generalshof 12, 10117 Berlin, Germany external_id: type: string description: Reference to be used in the customer's system example: 1538c2f9-ff0f-489e-0099-a5f116a4af07 vat_number: type: string description: The VAT number of the business example: BE09999999XX. register_number: type: string description: >- The registry number of the business (i.e. company house number, SIRET, SIREN, P.IVA, only GB, FR and IT companies are supported) example: '12345678' country_code: type: string description: Country code in ISO 3166-1 alpha-2 format example: DE description: type: string description: The description of the business example: Software consultancy registry_profile: type: string enum: - FULL - BASIC contact_person: $ref: '#/components/schemas/ContactPerson' risk_check_set_id: type: string description: >- The risk check set id, if not set the default risk check set will be used example: 550e8400-e29b-41d4-a716-446655440000 pull_registry_documents: type: boolean description: >- Whether to pull registry documents for the company (Only supported for DE, and IT) default: false example: true trading_name: type: string description: The trading name (DBA) of the business nullable: true example: Acme Trading Co trading_address: type: string description: The trading address of the business nullable: true example: 123 Trade Street, London CDDInput: type: object description: What was used to perform the CDD properties: website: type: string description: The website of the business example: https://example.com email: type: string description: The email of the business example: fulan@domain.com legal_name: type: string description: The legal name of the business example: PayLane Sp. z o.o. registry_profile: type: string enum: - FULL - BASIC address: type: string description: The address of the business example: Am Generalshof 12, 10117 Berlin, Germany external_id: type: string description: Reference to be used in the customer's system example: 1538c2f9-ff0f-489e-0099-a5f116a4af07 vat_number: type: string description: The VAT number of the business example: BE09999999XX. ValidationErrorItem: type: object properties: path: type: array items: type: string description: JSON path to the field with the error message: type: string description: Error message code: type: string description: Error code indicating the type of error required: - path - message - code ContactPerson: type: object description: >- Contact person details. At least one of 'name' or 'email' must be provided if the object exists. properties: name: type: string nullable: true minLength: 1 description: Name of the contact person email: type: string nullable: true format: email description: Email address of the contact person country_code: type: string nullable: true description: Country code of the contact person address: type: string nullable: true description: Address of the contact person phone_number: type: string nullable: true description: Phone number of the contact person ip: type: string nullable: true format: ipv4 description: IP address (IPv4 or IPv6) associated with the contact person anyOf: - required: - name - required: - email - required: - phone_number securitySchemes: xApiKey: type: apiKey name: X-API-KEY in: header ````