Webhook Configuration
This page covers webhooks for OpenNode, a legacy per-merchant option. Strike is the default payment provider, and new accounts should start there. Unless you have a specific reason to stay on OpenNode, see Strike Webhooks.
Lightning Enable forwards OpenNode payment events to your callback URL, signed with your webhook secret.
How It Works
- OpenNode → Lightning Enable. Each charge Lightning Enable creates carries its own callback URL, so you configure nothing in the OpenNode dashboard.
- Lightning Enable → your server. Lightning Enable forwards a signed, flat JSON payload to the URL you set below.
Configure Webhooks
Step 1: Set Your Webhook URL and Secret
Generate a secret (for example, openssl rand -hex 32), keep a copy, and set both with the merchant API. Lightning Enable never returns the secret, and your account's initial secret is not readable, so set your own.
curl -X PUT https://api.lightningenable.com/api/merchant/webhook-url -H "X-API-Key: your-merchant-api-key" -H "Content-Type: application/json" -d '{
"webhookUrl": "https://your-site.com/webhooks/lightning",
"webhookSecret": "your-webhook-secret"
}'
Step 2: Verify the Signature
Every delivery carries X-LightningEnable-Signature: t={timestamp},v1={hex_hmac}. The HMAC-SHA256 is computed with your secret over {timestamp}.{raw_body}. Reject timestamps older than 5 minutes and compare in constant time.
Use the reference verifiers in Verifying Webhooks rather than writing your own.
Webhook Payload
Lightning Enable forwards a flat JSON object per payment event — there is no envelope and no event field. For OpenNode-configured merchants the payload is:
{
"invoiceId": "1042",
"orderId": "ORDER-12345",
"status": "paid",
"amount": 49.99,
"currency": "USD",
"openNodeChargeId": "abc123-def456-...",
"paidAt": "2026-07-03T12:05:00Z",
"metadata": "{\"customerId\":\"cust_42\"}"
}
statusis the payment status; route on it.paidis the fulfillment trigger. You may also seeprocessing(which includes OpenNode'sunderpaid),expired, andrefunded.invoiceIdis the Lightning Enable invoice ID (numeric string) fromPOST /api/payments.metadatais the metadata JSON string you supplied at payment creation (ornull).- Refunds do not generate merchant webhooks — poll
GET /api/refunds/{refundId}instead.
(On Strike or NWC the payload carries providerChargeId and provider in place of openNodeChargeId; see the Webhooks API reference.)
Webhook Requirements
Endpoint Requirements
- HTTPS in production (HTTP allowed for localhost)
- Return 200-299 status code within 10 seconds (the delivery request times out after 10s)
- Accept POST requests with JSON body
Headers Sent
| Header | Description |
|---|---|
Content-Type | application/json |
X-LightningEnable-Signature | Timestamped HMAC-SHA256 signature (t={timestamp},v1={hmac}) |
Delivery & Reliability
Treat webhooks as a fast-path notification, not a guaranteed delivery channel:
- Each delivery attempt has a 10-second timeout; the first attempt fires as soon as Lightning Enable processes OpenNode's webhook.
- If your endpoint is down or errors, delivery is retried with exponential backoff (30s, 60s, 120s, 240s, 480s). Every attempt sends identical payload bytes with a freshly timestamped signature, so dedupe on
invoiceId+status, never on the signature header. - After retries exhaust, the event is marked permanently failed — recover by polling.
Recovery pattern: reconcile pending orders via GET /api/payments/{invoiceId} (authoritative), or force a provider re-check with POST /api/payments/{invoiceId}/sync.
Testing Webhooks
Local Development
Use ngrok to expose your local server:
# Terminal 1: Start your server
npm start # http://localhost:3000
# Terminal 2: Start ngrok
ngrok http 3000
# Copy the ngrok URL (e.g., https://abc123.ngrok.io)
# Use as your webhook URL
Send Test Webhook
To send a properly signed test webhook:
# Set your variables
WEBHOOK_SECRET="your-webhook-secret"
TIMESTAMP=$(date +%s)
PAYLOAD='{"invoiceId":"1042","orderId":"TEST-001","status":"paid","amount":10.00,"currency":"USD","openNodeChargeId":"test-charge","paidAt":"2026-07-03T12:05:00Z","metadata":null}'
# Compute the signature
SIG=$(echo -n "${TIMESTAMP}.${PAYLOAD}" | openssl dgst -sha256 -hmac "${WEBHOOK_SECRET}" | cut -d' ' -f2)
# Send the webhook
curl -X POST https://your-ngrok-url.ngrok.io/webhooks/lightning \
-H "Content-Type: application/json" \
-H "X-LightningEnable-Signature: t=${TIMESTAMP},v1=${SIG}" \
-d "${PAYLOAD}"
Troubleshooting
Webhooks Not Received
- Check URL - Verify webhook URL is correct
- Check HTTPS - Production requires HTTPS
- Check firewall - Allow incoming connections
- Check your server logs - and reconcile missed events via
POST /api/payments/{invoiceId}/sync
Signature Mismatch
- Raw body - Use the raw request body, not re-serialized JSON
- Correct secret - Verify webhook secret matches what you configured
- Correct header - The header is
X-LightningEnable-Signature, notX-Webhook-Signature - Signed payload format - HMAC is computed over
{timestamp}.{payload}, not just the payload - Encoding - Use UTF-8 encoding
Timeouts and Duplicates
Return 2xx within 10 seconds and do slow work afterward. Deliveries can repeat, so make your handler a no-op for an invoiceId + status you have already processed.
Next Steps
- Testing - Test your integration
- Webhooks API - API reference
- First Payment - Complete a test payment