Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt

Use this file to discover all available pages before exploring further.

Lumin webhooks require a publicly accessible HTTPS URL. During development, your local server isn’t reachable from the internet. A tunneling tool like ngrok solves this by creating a secure public URL that forwards requests to your local machine.

​
Prerequisites

Before you start:
  • A local web server running on a known port (e.g., Express.js on port 3000)
  • An ngrok account — the free tier is sufficient
  • A webhook endpoint in your application that accepts POST requests

​
Set up your local server

If you don’t have a webhook endpoint yet, here’s a minimal example: 
const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhook", (req, res) => {
  console.log("Webhook received:", JSON.stringify(req.body, null, 2));
  res.status(200).json({ status: "ok" });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
Log the full payload to your console so you can inspect the event structure as you test.

​
Expose your local server with ngrok

1

Install ngrok

Follow the ngrok installation guide for your operating system.
2

Start your local server

Make sure your application is running. For the example above:
node server.js
3

Start the ngrok tunnel

Run ngrok against the port your server is listening on:
ngrok http 3000
ngrok displays a public URL in the terminal output — for example:
Forwarding  https://abc123.ngrok-free.app -> http://localhost:3000
Use the https:// URL. Do not use the http:// URL — Lumin requires HTTPS.
4

Configure the webhook URL in Lumin

  1. Go to Settings → Developer settings → API Key tab → Account callback section.
  2. Enter your full ngrok URL including your endpoint path — for example, https://abc123.ngrok-free.app/webhook.
  3. Click Save.
5

Trigger a test event

Perform an action in Lumin that fires an event — for example, create a signature request to trigger signature_request_created. Watch your terminal for the incoming request.

​
Example payload

When a webhook arrives, your console will show a payload like this: 
{
  "event": {
    "event_time": 1758812613960,
    "event_type": "signature_request_created",
    "event_metadata": {
      "signer_email": "[email protected]",
      "workspace_id": "68d417..."
    }
  },
  "signature_request": {
    "signature_request_id": "68d559...",
    "title": "Test webhook",
    "created_at": 1758812612210,
    "updated_at": 1758812612248,
    "expires_at": 1827510980694,
    "status": "NEED_TO_SIGN",
    "signers": [
      {
        "name": "Signer 1",
        "email": "[email protected]",
        "status": "NEED_TO_SIGN",
        "is_approved": false
      }
    ],
    "details_url": "https://sign.luminpdf.com/auth?mode=view-contract&token=..."
  }
}

​
Tips for debugging

Log the raw request body. Before parsing JSON, log the raw body string — this is what Lumin signs with HMAC-SHA256 for the X-Signature header. Parsing and re-serializing can alter whitespace and break signature verification. Check the X-Signature header. Use the verification steps in Account webhooks to confirm your signature validation logic works correctly before deploying. Watch the ngrok inspector. ngrok provides a local web interface at http://localhost:4040 that shows each request and response in detail, including headers and body. This is useful for debugging without modifying your server code.

​
Important limitations with ngrok

Free ngrok sessions expire after 2 hours, and each restart generates a new URL. Remember to update your webhook URL in Lumin every time you restart ngrok.
  • Always use the https:// URL, not http://
  • The free tier has rate limits on incoming requests
  • ngrok URLs are not suitable for production — deploy to a stable HTTPS endpoint before going live

​
Next steps

Once your local testing is working:
  1. Deploy your webhook handler to a production server with a stable HTTPS URL.
  2. Update the webhook URL in Settings → Developer settings.
  3. Set up monitoring and alerting for failed deliveries.
See Account webhooks and App webhooks for full configuration details.