Webhook: Veriff

These instructions are required for: https://generalbytes.atlassian.net/wiki/x/AQDoog

Veriff notifies CAS via a webhook after verification has completed. The Veriff webhook must be configured to be exposed as HTTPS on the standard HTTPS port 443 on your hostname domain. You cannot use a custom port (i.e. 7743, 8743) with Veriff.

The webhook endpoint on the CAS server must be configured to be:

publicly visible on the internet (or at least to Veriff IP addresses), and
uses a valid HTTPS certificate (not just self-signed), and
assigned to a FQDN hostname (not just an IP address), and
which matches the contents of: /batm/config/hostname, and
complies with the RFC 952 host naming conventions (letters, digits, and hyphens only), and
exposes that HTTPS on the standard HTTPS port (443).

You have 2 options to accomplish this end:

Option A (free): NGINX with Let’s Encrypt

This free option requires you to only install and configure NGINX as a reverse proxy server. The CAS program batm-manage can handle most of the heavy lifting for this.

https://generalbytes.atlassian.net/l/cp/nfb1x7Xd

Option B (paid): NGINX with Cloudflare Zero Trust

Cloudflare offers Zero-Trust tunneling to those who use their paid Cloudflare DNS hosting.

https://generalbytes.atlassian.net/wiki/x/AwB7rw
Use with NGINX to protect your server from URL traversal attacks.

NGINX configuration

This configuration block differs between the Cloudflare and Let’s Encrypt approaches.

Both (common) approaches:
- the webhook endpoint = https://veriffwh.yourcasdomain.com/

Choose one of these 2 methods:

Let’s Encrypt:
- Requires an “A” record to assign a dedicated subdomain for Veriff.
- Open port 443 in your firewall, see: Configuring Server Firewalls
Cloudflare:
- create a tunnel (and automatic subdomain): veriffwh
- use: https://localhost:8720 in your tunnel.

Let’s Encrypt (only) server block

Create this server block specifically for Veriff webhooks exposed by a DNS “A” record:

sudo nano /etc/nginx/conf.d/veriffwh.conf

Enter this typical block in the file (modified as described here: NGINX server blocks):

server {
    listen       443 ssl;
    server_name veriffwh.yourcasdomain.com;
    ssl_certificate /etc/letsencrypt/live/yourcasdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourcasdomain.com/privkey.pem;
    access_log /var/log/nginx/veriffwh_access.log;
    error_log /var/log/nginx/veriffwh_error.log;
    location / {
        proxy_pass https://10.3.2.1:7743/serverapi/apiv1/identity-check/veriffwh;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Replace yourcasdomain.com with your actual domain.
Save & exit with Ctrl+X, “y”, and don’t change the filename; it helps identify the purpose.

Cloudflare (only) server block

This NGINX server block will expose the webhooks to Cloudflare: https://localhost:8720

For specific NGINX instructions, see: NGINX as a Reverse Proxy Server

Create this server block specifically for Cloudflare tunnels:

sudo nano /etc/nginx/conf.d/8720-veriffwh.conf

Enter this typical block in the file (modified as described here: NGINX server blocks):

server {
    listen       8720 ssl;
    server_name veriffwh.yourcasdomain.com;
    access_log /var/log/nginx/veriffwh_access.log;
    error_log /var/log/nginx/veriffwh_error.log;
    location / {
        proxy_pass https://10.3.2.1:7743/serverapi/apiv1/identity-check/veriffwh;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Replace yourcasdomain.com with your actual domain.
Save & exit with Ctrl+X, “y”, and don’t change the filename; it helps identify the purpose.
Configure your Cloudflare tunnel to forward it as desired.

Test the webhook endpoint

Before proceeding, you should have a working endpoint.

https://help.veriff.com/en/articles/3430232-what-are-webhooks

You can test that your server is configured correctly by entering the webhook URL in your browser. Visit this URL: https://veriffwh.yourcasdomain.com

Replace yourcasdomain.com with your actual domain name.

Make sure there are no SSL warnings.

The lock icon in the URL should be closed / locked and it should say “secure”.

The website should contain this following simple text: “BATM server endpoint for Veriff webhooks”

Security:

Contact your Veriff account manager to get the Veriff IP range for webhook listeners.

If you only use Veriff, blacklist all public access to your published port (using UFW), then:

whitelist the Veriff IP range for webhook listeners.