Webhook: Sumsub

Sumsub communicates with CAS via a webhook. This article describes how to create a webhook endpoint for Sumsub via NGINX. This method is the same for all Sumsub articles:

Enable the webhook in CAS:

Create the following file: /batm/config/sumsub
1. e.g. sudo nano /batm/config/sumsub
Enter this single line: webhooksEnabled=true
Save and exit nano (Ctrl+X, “y”, name sumsub).

Setup the webhook endpoint in NGINX.

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

publicly visible on the internet (or at least to Sumsub IP addresses), and
using a valid HTTPS certificate (not just self-signed), and
assigned to a FQDN hostname (not just an IP address), and
complies with the RFC 952 host naming conventions (letters, digits, and hyphens only).

You have 2 options to expose the webhook:

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 server block

This configuration block is common to both Cloudflare and Let’s Encrypt approaches.

Exposes the /sumsubwh endpoint on port 8706.
Let’s Encrypt:
- Open port 8706 in your firewall, see: Configuring Server Firewalls
- the webhook endpoint = https://yourcasdomain.com:8706/sumsubwh
Cloudflare:
- create a tunnel (and subdomain): sumsub
- use: https://localhost:8706 in your tunnel,
- the webhook endpoint would then be: https://sumsub.yourcasdomain.com/sumsubwh

Create this server block specifically for Sumsub webhooks:

sudo nano /etc/nginx/conf.d/8706-sumsub.conf

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

server {
    listen       8706 ssl;
    server_name sumsubwh;
    access_log /var/log/nginx/sumsub_access.log;
    error_log /var/log/nginx/sumsub_error.log;
    location /sumsubwh {
        proxy_pass https://10.3.2.1:7743/serverapi/apiv1/identity-check/sumsubwh;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # insert your Let's Encrypt certificate and key here if using that method
    }
}

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

Test the webhook endpoint

You must have a working public endpoint for Sumsub to communicate with CAS. A Sumsub account is not required at this point, and this endpoint should be 100% functional before creating your Sumsub API tokens.

Make sure there are no SSL warnings in your browser.
- The lock icon in the URL should be closed / locked and it should say “secure”.
Navigate to the appropriate URL in a browser:
- Let’s Encrypt: https://yourcasdomain.com:8706/sumsubwh
- Cloudflare tunnel: https://sumsub.yourcasdomain.com/sumsubwh
- Replace yourcasdomain.comwith your actual CAS domain name.
- The browser should display simply: “BATM server endpoint for SumSub webhooks”.