LuniPay Docs

API Reference

Webhook Endpoints

A webhook endpoint is a URL on your server that LuniPay calls when events happen. Register one per environment, store the signing secret, and verify every request.

Webhook endpoints must be publicly reachable HTTPS URLs. For local development, expose your local handler with ngrok or Cloudflare Tunnel and register the public HTTPS URL. Endpoints are scoped per livemode — a test-mode endpoint never receives live events, and vice versa. LuniPay signs every delivery with HMAC-SHA256 over `timestamp.payload` and sends it as `LuniPay-Signature: t=...,v1=...`. Failed deliveries retry with exponential backoff over ~10.5 hours.

Working example

Start here if you just need a known-good request. The cURL, Node.js, and Python tabs show the same API call.

curl https://www.lunipay.io/api/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/lunipay",
    "enabled_events": ["checkout.session.completed", "payment.succeeded", "payment.failed"],
    "description": "Production webhook receiver"
  }'
{
  "id": "we_01JRZKC5PRGHKV82AW7XNMFD9H",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://example.com/webhooks/lunipay",
  "description": "Production webhook receiver",
  "enabled_events": [
    "checkout.session.completed",
    "payment.succeeded",
    "payment.failed"
  ],
  "is_active": true,
  "signing_secret": "whsec_shown_once_on_create_only",
  "created": 1713100800,
  "updated": 1713100800
}

The webhook_endpoint object

idstring

Unique identifier, prefixed with `we_`.

objectstring

Always `"webhook_endpoint"`.

livemodeboolean

Whether this endpoint receives test or live events.

urlstring

Your public HTTPS URL that receives POST deliveries. `http://localhost` is not accepted; use a tunnel for local testing.

descriptionstringnullable

Internal label for the dashboard.

enabled_eventsarray

List of event types this endpoint subscribes to. Use `["*"]` to receive everything.

is_activeboolean

Pause deliveries without deleting the endpoint.

signing_secretstring

The `whsec_…` secret used to verify request signatures. **Only returned once — on create.** Store it immediately.

createdinteger

Creation timestamp (unix).

updatedinteger

Last-updated timestamp (unix).

{
  "id": "we_01JRZKC5PRGHKV82AW7XNMFD9H",
  "object": "webhook_endpoint",
  "livemode": false,
  "url": "https://example.com/webhooks/lunipay",
  "description": "Production webhook receiver",
  "enabled_events": [
    "checkout.session.completed",
    "payment.succeeded",
    "payment.failed"
  ],
  "is_active": true,
  "signing_secret": "whsec_shown_once_on_create_only",
  "created": 1713100800,
  "updated": 1713100800
}

Endpoints