Webhook: Global Travel Rule (GTR)

This article required by the Global Travel Rule (GTR) API : GTR Travel Rule Provider

GTR communicates with CAS via a webhook. This article describes how to create a webhook endpoint for GTR via NGINX. You’ll need to expose the CAS REST API to the GTR servers.

Create GTR Webhook Certificates

This folder will contain certificates required for GTR to successfully connect to CAS.

Make the directory:

sudo mkdir /batm/config/gtr_certs

Create these 2 certificates:

Create a PEM certificate:

sudo openssl s_client -connect uat-platform.globaltravelrule.com:443 -showcerts </dev/null | openssl x509 -outform PEM > /batm/config/gtr_certs/gtr_server_trust_certificate.pem

Create a p12 certificate:

sudo openssl pkcs12 -export -out /batm/config/gtr_certs/server.p12 -inkey /batm/config/gtr_certs/privateKey.pem -in /batm/config/gtr_certs/certificate.pem -passout pass:123456

The certficates should now be present in the /batm/config/gtr_certs folder.

sudo ls /batm/config/gtr_certs

Configure the GTR settings on the CAS console:

Create the file /batm/config/gtr

sudo nano /batm/config/gtr

Add these lines to the file:

apiUrl=https://uat-platform.globaltravelrule.com
RequestIdPrefix=Example
clientCertificatePassphrase=Example123456 
clientCertificatePath=gtr_certs/certificate.p12
gtrServerTrustCertificatePath=gtr_certs/gtr_server_trust_certificate.pem
webhooksEnabled=true

The filenames listed must match the certificate filenames created in the previous step.
Save and exit nano (Ctrl+X, “y”, required filename: gtr).

Setup the webhook endpoint in NGINX.

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

publicly visible on the internet (or at least to GTR 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).
The GTR webhook CANNOT use a non-standard port (it must use port 443).

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 configuration

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

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

Choose one of these 2 methods:

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

Let’s Encrypt (only) server block

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

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

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

server {
    listen       443 ssl;
    server_name gtr.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/gtr_access.log;
    error_log /var/log/nginx/gtr_error.log;

    location / {
        proxy_pass https://10.3.2.1:7743/extensions/gtr/webhooks;
        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:8740

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/8750-gtr.conf

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

server {
    listen       8750 ssl;
    server_name gtr.yourcasdomain.com;

    access_log /var/log/nginx/gtr_access.log;
    error_log /var/log/nginx/gtr_error.log;

    location / {
        proxy_pass https://10.3.2.1:7743/extensions/gtr/webhooks;
        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.