Webhook Events

When the outcome of your insurance orders changes, Lunixi sends insurance.* events to your endpoint: the policy was issued, could not be issued, its document is ready, it was cancelled, a premium refund is required or completed; a claim was passed to the provider or could not be passed; a lead was passed to the provider. The events are the same on the Checkout Form path and on the API path.

Delivery, signature verification and retries are the same for all products: Webhooks.

Events

insurance.policy.issued

Sent when the order's policies are issued. data.policyStatus becomes ISSUED; the policy numbers are in data.policies[].policyNumber.

The document may not be ready yet at this point (documentStatus: PENDING). When it is ready, insurance.policy.document_ready is sent as well.

The policy outcome may be finalized late. If insurance.policy.failed (and insurance.refund.required) was sent for an order first and the refund has not started yet, insurance.policy.issued is also sent when the policy is issued later. In that case data.refundStatus is NONE; the premium refund is no longer required.

insurance.policy.failed

Sent in three cases:

If the premium was collected, insurance.refund.required is sent at the same time.

insurance.refund.required

Sent when the premium was collected but the policy could not be issued, finally. On the order, the policy becomes FAILED_FINAL and the refund REQUIRED. errorCode shows why the policy could not be issued.

When you receive the event, read the order from the order endpoint:

• If refundStatus is PENDING or REFUNDED, the refund has started; insurance.refund.completed is sent when it completes.
• If refundStatus is REQUIRED, refund the premium with the premium refund endpoint. If you collected the premium outside Lunixi, make the refund through your own channel and report it with the same endpoint.

The premium refund request can be repeated: if the refund has already started, the order is returned as is.

insurance.policy.document_ready

Sent when the documents of the order's issued policies are verified with the provider. data.documentStatus becomes AVAILABLE.

Download the document from data.policies[].documentUrl. This address is the Policy Document endpoint; you sign the request with your API key like your other API requests. The address does not carry any authorization by itself, and the document is not stored at Lunixi.

insurance.policy.cancelled

Sent when the provider finalizes the cancellation of all policies of the order. data.policyStatus becomes CANCELLED. The document of a cancelled policy cannot be retrieved; documentUrl is an empty string.

Cancelling the policy does not refund the premium. The premium refund is a separate step, and insurance.refund.completed is sent when it completes. See Cancellation and Premium Refund.

insurance.refund.completed

Sent when the premium refund is completed. data.refundStatus becomes REFUNDED.

• If the premium was collected in a Lunixi payment, the event is sent when the refund is made from the payment.
• If you collected the premium outside Lunixi, the event is sent when you report the refund with the premium refund endpoint.

insurance.claim.submitted

Sent when a claim reaches the provider and the provider records it. The claim is in data.claim; data.claim.status becomes SUBMITTED. You can get the provider's claim document from the claim document endpoint.

The event does not carry the assessment result of the claim; the assessment is done by the insurance company.

insurance.claim.failed

Sent when a claim is not accepted by the provider or does not reach the provider. data.claim.status becomes FAILED; the reason is in data.claim.errorCode:

If needed, you can file a new claim for the same policy: Claims.

insurance.lead.submitted

Sent when a lead reaches the provider and the provider receives it. The lead is in data.lead; data.lead.status becomes SUBMITTED. Because a lead is not linked to an order, the data of this event does not carry order fields: Lead event payload.

The event does not carry the provider's steps after the lead (contacting the buyer, an offer).

Cases without an event

No event is sent for the following cases. Track them on the order endpoint:

Delivery structure

The delivery body is an envelope; the order's fields are under data.

Envelope

The envelope may contain fields not in this table; base your code only on the fields documented here.

data

data carries the order state after the transition the event describes. The data of the lead event is different: Lead event payload.

Values of the status axes: Concepts › Order statuses.

policies[]:

claim (only in insurance.claim.* events):

In claim events, the order's other fields carry the order's status at the time of the event. The document and the provider's claim reference are not included in the payload.

Lead event payload

The data of the insurance.lead.submitted event carries only these fields:

lead:

The lead body, the note and personal data, the provider's name and the lead reference are not included in the payload. Use the retrieve endpoint for the lead's masked view.

In webhooks, fields without a value come as null; the field is still present in the body. Personal data and the provider's own references are not included in the payload.

Subscription

To receive the events, create a webhook endpoint for the insurance product:

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": "Insurance events — test",
    "url": "https://merchant.example.com/webhooks/lunixi",
    "productCode": "INSURANCE_SERVICE",
    "environment": "TEST",
    "secretRef": "vault:<secretId>",
    "eventTypes": ["insurance.*"]
  }'

Creating the endpoint, the signing secret and delivery history: Webhook Setup.

Signature, retries and deduplication

Verify the signature on every delivery; the signature format and retry policy are the same for all products: Webhooks.

• Delivery is at least once. The same event may arrive more than once. Process the event idempotently by x-lunixi-event-id. The same event carries the same ID on every delivery; this value is also the same as data.eventId.
• Do not rely on the order. A retried delivery may arrive after a later event. Derive the order's latest state from the status axes in data, not from the order of events. When in doubt, read the order from the order endpoint.
• Respond to the event quickly. Verify the signature, write the event to your own queue and return 2xx. Do work such as downloading the document after the response.

Using the webhook with the order endpoint

The webhook is the fast way to learn the order's outcome; it is not the only source. If your endpoint is unreachable for a while, or the status changed through a path without an event (table above), read the order from the order endpoint. data.insuranceOrderId from the webhook is the same as orderId on the order endpoint.

Related

• Error Codes: meaning of the errorCode values
• Concepts and Statuses: status axes and overall status
• Orders and Payment Binding: the order object