Set up the PV service in a Test environment

How to set up the KWS Parent Verification service for your product(s) in a Test environment.

To set up your Test environment, create your excluded, product in KWS and then link the PV service to it, as follows.

Set up your product

  1. In the KWS Developer Portal's Dashboard tab, click the Add product button in the top right corner:

  2. Enter the Product name and click Add product:

    The product now exists in your test environment. You are prompted to complete the product details.

  3. Enter the Basic information and agree to the service terms and conditions:

    • Product name

    • Product URLs - The verification request email that KWS sends to the parent includes links to these URLs:

      • Privacy policy - The URL for your organization's privacy policy.

      • Customer support / FAQ - The URL for your organization's support/FAQs.

Set up the service

When you have accepted the service terms and conditions, the service details become available for editing. These consist of your redirect URL and webhook settings:

Set up the redirect URL

Enter a RedirectURL. This is the URL that KWS redirects parents to on successful or ultimate failure of verification. It is in this format:

https://your.domain.com/your/path?status=...&externalPayload=...

where:

  • externalPayload is the optional external payload passed into the initiate call.

  • status is a URL encoded JSON object representing the status returned from verification:

    {
    verified: boolean,
    transactionId: string,
    errorCode: string | null,
    }

NOTE: The information in the redirect URL is not signed and may be modified by the user. It should only be used for presentation purposes, not to determine the result of the verification. You should use a webhook to determine the result.

If no URL is configured, KWS shows a success/failure page within its widget.

Set up the webhook

KWS notifies your systems of events via a webhook call. To set up the webhook:

  1. In the Parent Verification Service view, enter the Successful verification webhook address. This is where KWS sends the webhook that confirms successful verification.

    IMPORTANT: Do not include information in the webhook URL that is sensitive to manipulation by an attacker (for example, numeric IDs that may be iterated over easily). The URL is intentionally not part of the signature algorithm to allow easier signature validation within services behind reverse-proxies/load-balancers etc. when the request URL may be modified.

  2. Copy the following values for use in your webhook configuration:

    • Webhook secret code - This is the webhook secret key used to sign the payload to ensure it is a genuine call from KWS.

    • Service API host URL

    • Service widget URL

POST body structure

All webhook calls are HTTPS POSTs with a common structure wrapping the event-specific payload:

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=1621535329,v1=f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
Body
{
  "name": "webhook-name",
  "time": "ISO8601 timestamp",
  "orgId": "uuid",
  "productId": "uuid" | null,     // Future webhooks may apply at org level
  "environmentId": "uuid" | null,
  "payload": { ... type-specific payload ... }
}

Signatures

Signatures are a HMAC_SHA256 hash in hex format (lowercase), where the secret key is the Webhook secret code you provide in the webhook settings.

They are sent in a x-kws-signature header in the following format:

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

Currently only a single v1 signature will be included, but the header may contain multiple signatures if/when:

  • Signature key rotation is supported (signatures will be sent for previous and current keys for a transitionary period).

  • The signature algorithm changes (v2 signatures will be sent alongside v1 signatures for a transitionary period).

The algorithm to generate v1 signatures is a HMAC_SHA256 of the timestamp included in the signature header, followed by a period (‘.') followed by the raw request body. The HMAC should be initialized with your webhook's secret key.

For example:

const timestamp = /* extracted value of ‘t=' from the header */;
const body = /* raw request body as UTF-8 string */;
const secretKey = /* secret key, as entered in dev portal */;
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(`${timestamp}.${body}`)
  .digest('hex');

NOTE: It is important that the raw POST body is used. Do not attempt to parse and re-stringify the JSON as this may result in mismatched signatures due to inconsistencies in JSON library implementations.

Service configuration review

Before you can start testing your integration, KWS will review your service configuration details. Any products created in either the Test or Production environment must undergo a review process that is overseen by a KWS admin. When you click Save, the review process is initiated.

We will notify you when your configuration has been reviewed and, if it doesn't pass the review process, inform you of the reason for rejection. We typically review a excluded, product within 7 business days, Monday to Friday. During periods of high demand this may take longer.

Delete a product

To delete a excluded, product from your KWS organization:

  1. In the KWS Developer Portal's Dashboard, find the required product.

  2. Click Delete.

When a excluded, product is deleted:

  • All branding applied to the product in the Developer Portal is deleted.

  • All services linked to the product are disabled.

Tags