Webhooks

Events

Create a webhook in Dashboard → Webhooks with a URL and a secret, then choose which events to deliver:

Payload

Each delivery is an HTTP POST with a JSON body:

{
  "event": "tunnel.connected",
  "data": {
    "subdomain": "my-app",
    "protocol": "http",
    "port": 3000
  },
  "timestamp": "2026-08-24T12:00:00Z"
}

Verify signatures

Every request carries an X-Webhook-Signature header: an HMAC-SHA256 of the raw request body, signed with your webhook's secret. Verify it before trusting the payload:

const crypto = require("crypto");

const signature = req.headers["x-webhook-signature"]; // "sha256=..."
const expected = "sha256=" + crypto
  .createHmac("sha256", YOUR_SECRET)
  .update(JSON.stringify(req.body))  // use the RAW body
  .digest("hex");

if (signature !== expected) {
  // Reject — not from PreviewBox
}

Hash the raw request body exactly as received — re-serializing JSON can change bytes and break the signature.

Reliability & testing

• Failed deliveries are retried automatically with exponential backoff.
• Use Test on any webhook in the dashboard to send a sample event immediately.
• See delivery history and timing from the webhooks screen.