Webhooks are one way that apps can send automated messages or information to other apps. They're a simple way your online accounts can "speak" to each other and get notified automatically when something new happens. In many cases, you'll need to know how to use webhooks if you want to automatically push data from one app to another.

Webhooks are automated messages sent from apps when something happens. They have a message, or payload, and are sent to a unique URL.

Enveloped Application Scheme

Download Here

Create a New General Webhook

To create a Webhook, you should set up an URL to receive information on events of apps' verification results and SDK events.

Important!

We do NOT accept HTTP or Self-signed certificates.

Create a New Webhook for a specific SDK Flow only

Important!

Attention! If you enable this option in your SDK Flow, the General Webhook(/settings/webhooks) will be disabled. For API, you still have to use General Webhook /settings/webhooks

:::

The option helps you to set up a specific Webhook to any SDK Flow.

Use case: A Client has two offices:

1. For the UK, you set a specific webhook for the SDK Flow Webhook URL of the UK Office. Only the UK office will receive all verifications from the UK SDK Flow
2. For Germany, you set a specific webhook for the SDK Flow Webhook URL of the German Office. Only the German office will receive all verifications from the German SDK Flow

Webhook Settings Page

1. Settings → Webhooks (SDK Webook settings: Flow tab → Choose/Create any SDK Flow → Webhooks tab) 
2. Create a Webhook

Webhook URL

This is your internal URL where you receive our messages.

Webhook Events

It's possible to activate/disable different events by checking/unchecking relevant combo boxes as needed.

Application Events

application.created

The application.created event is being sent once an application is created on the IDScan side, validated and relatively stored in the IDScan database.

application.verified

The application.verified event is being sent once the application verification process by all IDScan verification services is finished.

application.changed

The application.changed event is being sent once the final status of the application was manually modified in IDScan Administrative Portal by a client's specialists (e.g., app status update).

SDK Events

SDK Events are HTTP(S) callbacks on events that just occurred on verification steps of SDK clients’ side.

sdk.init

The sdk.init event is being sent once the SDK configuration is requested from the IDScan server by a Client. SDK is initialised.

sdk.completed

The sdk.completed event is being sent once all needed data gathering process for verification within SDK is completed.

Note:

This event is sent before the application.created event

Signature key

Use this key to validate that the content isn’t tampered with and that the sender is IDScan .

Should you wish to get a new public key by pressing the Generate new key button, a warning message appears informing you that the old key would be removed without a possibility to restore it, and asking whether you wish to proceed:

Click the Yes button to proceed or Cancel to abort the procedure.

To verify the signature (which is located in the X-Signature header), concatenate the HTTP body with the X-Timestamp header as strings and verify it with the obtained public key.

EdDSA / Ed25519 algorithm is used to sign and verify the webhook's content.

Some programming languages already support the algorithm natively, such as Node.js, Go. Some programming languages have this algorithm inside the widely used libraries: PyPI,  Python-Pynacl, C.

Example of validating the signature using Python- PyPI

import base64

from cryptography.hazmat.primitives.serialization import load_pem_public_key


public_key_pem = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAzwNEYKx7eenibHyTOz0i/NGsy9qEelrYF+RqntByOsE=\n-----END PUBLIC KEY-----\n"
signature = "jRo8odJVbc8MkF3B4967Q4Rm7bPSFvya3P8taTGNYo8NQAboDFoJfA9PiWa7lHBgEnd+HoLqKucumauS/jjtDQ=="

body = '{"id":"619e1639d3cae3747dc12340"}'
timestamp = "1637750331081"

msg = body + timestamp
signature_bytes = base64.b64decode(signature)
public_key = load_pem_public_key(public_key_pem.encode('utf8'))

print('Verifying...')
public_key.verify(signature_bytes, msg.encode('utf8'))
print('OK')

Example of validating the signature using Node JS:

const express = require('express');
 const crypto = require('crypto');
 const app = express();
 app.use(express.urlencoded({ extended: false }));
 app.listen( 8000, () => {
    console.log( server started at port 8000 );
 });

 /* Signature key from settings page */

 const publicKey = '-----BEGIN PUBLIC KEY-----\n' +
 'MCowBQYDK2VwAyEAvGhtRZLKTfIWS/4K/P5tUvHeumX5l4MdwXdqYW0JxKk=\n' +
 '-----END PUBLIC KEY-----';

 app.post('/your_URL_to_handle_webhooks', async (req, res ) => {
     try {
         const timestamp = req.header('X-Timestamp');
         const signature = req.header('X-Signature');
         const msg = JSON.stringify(req.body).concat(timestamp);
         const valid = crypto.verify(
             null,
             Buffer.from(msg),
             publicKey,
             Buffer.from(signature, 'base64')
         );
         if(valid){
            // Do some stuff
         } else {
            // signature is not valid, data received from unknown caller
            // Do some stuff
         }
     } catch (e) {
        console.error(e);
     }
 });