Connect a customer action executor over HTTPS

​

How the connection works

https://actions.example.com/suppio/actions

​

What Suppio expects

​

Choose how to publish the executor

​

Option 1: VPS with Caddy

​

Before you start

• a VPS with a public IPv4 address or properly configured public IPv6 address
• SSH access with sudo
• a domain or subdomain you control
• the complete Node.js executor example, or an equivalent implementation in your stack
• the signing secret shown by the Suppio dashboard

const host = process.env.HOST ?? "127.0.0.1";
const port = Number(process.env.PORT ?? "8787");

app.get("/health", (_req, res) => {
  res.json({ ok: true });
});

const server = app.listen(port, host, () => {
  console.log(`Customer action executor listening on ${host}:${port}`);
});

server.on("error", (error) => {
  console.error("Customer action executor failed to start", error);
  process.exitCode = 1;
});

curl --fail --show-error http://127.0.0.1:8787/health

sudo useradd --system --home /opt/customer-actions --shell /usr/sbin/nologin customer-actions
sudo install -d -o customer-actions -g customer-actions /opt/customer-actions
sudo install -m 600 -o root -g root /dev/null /etc/customer-actions.env
sudoedit /etc/customer-actions.env

SUPPIO_ACTION_SECRET=PASTE_THE_SIGNING_SECRET_FROM_THE_DASHBOARD
ALLOWED_DISCORD_USER_IDS=123456789012345678
HOST=127.0.0.1
PORT=8787
DATA_DIR=/var/lib/customer-actions
NODE_ENV=production

[Unit]
Description=Customer action executor
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=customer-actions
Group=customer-actions
WorkingDirectory=/opt/customer-actions
EnvironmentFile=/etc/customer-actions.env
ExecStart=/usr/bin/node /opt/customer-actions/server.mjs
Restart=on-failure
RestartSec=5
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
StateDirectory=customer-actions
StateDirectoryMode=0700

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now customer-actions
sudo systemctl status customer-actions

sudo journalctl -u customer-actions --since "10 minutes ago"

Type: A
Name: actions
Value: YOUR_VPS_PUBLIC_IPV4_ADDRESS

dig +short actions.example.com

actions.example.com {
  @executor path /suppio/actions /health

  handle @executor {
    reverse_proxy 127.0.0.1:8787
  }

  respond 404
}

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

curl --fail --show-error https://actions.example.com/health

curl --silent --output /dev/null --write-out "%{http_code}\n" https://actions.example.com/not-an-action

https://actions.example.com/suppio/actions

sudo systemctl restart customer-actions
sudo systemctl status customer-actions

​

Option 2: Cloudflare Tunnel

Hostname: actions.example.com
Service URL: http://127.0.0.1:8787

curl --fail --show-error https://actions.example.com/health

​

Option 3: Managed application hosting

• the action route accepts direct HTTPS POST requests without a browser login
• the signing secret is stored in the platform’s secret manager, not in source code
• your framework exposes the original raw request body before JSON parsing
• the platform does not redirect the configured action path
• cold starts and action execution finish within 15 seconds
• the application accepts request bodies up to 64 KB
• the response body stays below 64 KB
• the application has a persistent database or durable store for action_id and event_id deduplication
• logs exclude signature headers, secrets, raw request bodies, arguments, and result data

​

The complete request lifecycle

1. Receive the HTTPS request at the exact configured path.
2. Limit how much request data the server accepts.
3. Read the timestamp and signature headers.
4. Reject a timestamp more than five minutes away from the executor’s clock.
5. Calculate the HMAC over the exact raw body and compare it in constant time.
6. Parse JSON only after the signature succeeds.

1. Confirm that X-Suppio-Action-Id matches action_id.
2. Return success without mutating data when event is customer_action.test.
3. Reject action names that are not in an explicit handler allowlist.
4. Validate every argument again in your application.
5. Authorize actor.user_id for the targeted account or resource.
6. Atomically claim action_id in durable storage. Return the stored result if that ID already completed, and never repeat a result whose completion is uncertain.
7. Perform the action once.
8. Store and return a succeeded or failed JSON result within 15 seconds. Return both known outcomes with HTTP 2xx.

1. Confirm that X-Suppio-Event-Id matches event_id.
2. Validate source, actor, conversation, and agent.
3. Atomically store event_id and the work your integration must perform. If the same ID arrives again, acknowledge it without creating duplicate work.
4. Return any 2xx response after the event is durably accepted. Suppio ignores the body.

​

Security checklist

• Bind the executor to 127.0.0.1 when a reverse proxy or tunnel runs on the same machine.
• Run the executor as a dedicated non-root user.
• Keep the signing secret in a protected environment file or secret manager.
• Verify signatures against raw bytes before parsing JSON.
• Keep the server clock synchronized so timestamp checks are reliable.
• Persist action_id and event_id values before applying side effects.
• Use explicit action handlers instead of dynamic code, commands, URLs, SQL, or unrestricted operation names.
• Validate and authorize arguments even though the action has a strict schema.
• Do not log secrets, signature headers, request bodies, action arguments, or executor result data.
• Rotate the signing secret immediately if it may have been exposed.
• Keep the operating system, runtime, reverse proxy, tunnel client, and dependencies updated.

​

Troubleshooting

​

Go-live checklist

• the public URL uses a valid HTTPS certificate
• the URL returns no redirect
• the executor listens only on loopback or through the intended private network
• the action path has no interactive access challenge
• the signing secret is stored outside source control
• signature and timestamp checks run before parsing, and the matching action ID or event ID is validated afterward
• every action name maps to one explicit handler
• durable idempotency is working
• known failures return HTTP 2xx with structured failure results
• the executor responds in less than 15 seconds
• Test connection succeeds
• the signed ticket.resolved smoke test returns 2xx when you use ticket closing notifications
• the endpoint and intended actions are enabled