Skip to main content

Webhook Configuration

Legacy provider

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​

  1. OpenNode → Lightning Enable. Each charge Lightning Enable creates carries its own callback URL, so you configure nothing in the OpenNode dashboard.
  2. 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\"}"
}
  • status is the payment status; route on it. paid is the fulfillment trigger. You may also see processing (which includes OpenNode's underpaid), expired, and refunded.
  • invoiceId is the Lightning Enable invoice ID (numeric string) from POST /api/payments.
  • metadata is the metadata JSON string you supplied at payment creation (or null).
  • 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​

HeaderDescription
Content-Typeapplication/json
X-LightningEnable-SignatureTimestamped 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​

  1. Check URL - Verify webhook URL is correct
  2. Check HTTPS - Production requires HTTPS
  3. Check firewall - Allow incoming connections
  4. Check your server logs - and reconcile missed events via POST /api/payments/{invoiceId}/sync

Signature Mismatch​

  1. Raw body - Use the raw request body, not re-serialized JSON
  2. Correct secret - Verify webhook secret matches what you configured
  3. Correct header - The header is X-LightningEnable-Signature, not X-Webhook-Signature
  4. Signed payload format - HMAC is computed over {timestamp}.{payload}, not just the payload
  5. 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​