Webhook Setup

This page covers the management side. The contract for an incoming delivery (headers, signature, retries) is on its own page: Webhooks.

You can manage endpoints from the panel or the API; both reach the same control plane.

Access requirements

• The Bearer principal must hold the webhooks:manage permission.
• The organization must have the webhook entitlement enabled — otherwise every call returns 403 webhook.entitlement.not_enabled.

Endpoints

All are relative to https://api-gateway.lunixi.com and require a Bearer token.

Endpoint fields

Event subscriptions belong to the endpoint and are per event type; you subscribe an endpoint only to the events it cares about. The DELETE behaviour is unchanged: it disables rather than deletes.

For bank account events, create the endpoint with productCode: "BANK_CONNECT" and eventTypes: ["bank_account.*"]; add "bank_transfer.*" to also receive transfer events. → Bank Accounts › Webhook Events

For insurance events, create the endpoint with productCode: "INSURANCE_SERVICE" and eventTypes: ["insurance.*"]. → Insurance › Webhook Events

Setup flow

curl -X POST "https://api-gateway.lunixi.com/api/v1/secrets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "<orgId>",
    "secretKey": "webhook/<orgId>/LIVE/PAYMENT_GATEWAY/<name>",
    "payload": { "signingSecret": "whsec_<your own random value, ≥32 chars>" }
  }'

curl -X POST "https://api-gateway.lunixi.com/api/v1/organizations/$ORG_ID/webhook-endpoints" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment events — live",
    "url": "https://merchant.example.com/webhooks/lunixi",
    "productCode": "PAYMENT_GATEWAY",
    "environment": "LIVE",
    "secretRef": "vault:<secretId>",
    "eventTypes": ["payment.*"]
  }'

Delivery history

curl "https://api-gateway.lunixi.com/api/v1/organizations/$ORG_ID/webhook-deliveries?status=DEAD_LETTER" \
  -H "Authorization: Bearer $TOKEN"

Filters: endpointId · eventType · status

Each delivery record carries attemptCount, lastErrorCode, lastError, nextRetryAt and deliveredAt. Attempts are also logged individually — you can see which HTTP status you returned on which attempt.

Replaying a failed delivery

curl -X POST "https://api-gateway.lunixi.com/api/v1/organizations/$ORG_ID/webhook-deliveries/$DELIVERY_ID/replay" \
  -H "Authorization: Bearer $TOKEN"

This is how a DEAD_LETTER delivery is recovered. If your endpoint was down for a period, list the deliveries in that window and replay them in bulk.

Rotating the secret

After you rotate, the platform dual-signs deliveries with both the old and the new secret for 24 hours (the "grace window"): the x-lunixi-signature header carries two v2= items. A verifier that accepts the signature when any v2= item matches — like the example on Webhooks — needs no changes at all. After 24 hours the old secret stops being used.

The sequence is simple:

1. Rotate, and write the new value to your vault.
2. During the grace window deliveries arrive with both signatures — if your verifier accepts any matching v2= item, there is no gap.
3. After 24 hours signing with the old secret stops; nothing further to do on your side.

If your endpoint was disabled

When the consecutive-failure threshold is crossed (default 20) the endpoint's status becomes FAILED and it stops receiving deliveries. After fixing your server, re-enable it from the panel; you can then replay the deliveries that accumulated meanwhile.

Related

• Webhooks — headers, signature, retries, delivery statuses
• Authentication — how you mint the Bearer token