API Reference · Webhook Endpoints

Create a webhook endpoint

Registers a new webhook endpoint. The signing secret is returned once.

POST/v1/webhook-endpoints

The `signing_secret` field is the only time you can read the plaintext secret. Store it in your server-side secret store — LuniPay encrypts it at rest and never shows it again.

Returnswebhook_endpoint object

Body parameters

urlstringRequired

HTTPS URL that will receive deliveries.

enabled_eventsarrayRequired

Event types to subscribe to. Use `["*"]` to receive everything.

descriptionstring

Optional dashboard label.

Errors

400

parameter_invalid_url

`url` is missing, not HTTPS, or malformed.

Request

curl https://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"
  }'

Response

{
  "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
}