Webhooks · Insurance Quote Status

Insurance Quote Status Event — API Guide 3 min read

When you accept an insurance quote with a Subscription.Webhook attached, the API Hub delivers an Insurance Quote Status Event to your registered URL each time the LFI emits a quote-log update. Events flow through the full lifecycle from ApplicationPending to a terminal state.

01 Prerequisites

What you need before events can be delivered

Before receiving an Insurance Quote Status Event, ensure the following requirements are met:

Registered Application — the application must be created within the Trust Framework and assigned the ISP role as defined in Roles.
Valid Encryption Certificate — an active encryption certificate must be issued and registered in the Trust Framework to receive the event as an encrypted JWE.
Accepted quote with a Subscription.Webhook — the webhook is registered per-quote on PATCH Accept (see Insurance Quotation API Guide).

02 How It Works

Push delivery on every quote-log status change

Insurance Quotation does not use a per-customer consent. The webhook subscription is attached to the quote itself when you PATCH Accept. From that point, every time the LFI emits a status to PATCH /insurance-quote-log/{logId}, the Hub delivers an Insurance Quote Status Event to your registered Webhook.Url as a JWE-encrypted POST.

The JWE is encrypted using your public Encryption Certificate. You must respond with 202 Accepted immediately and decrypt the event payload asynchronously.

03 Step 1

Subscribe on PATCH Accept Quote

Attach a Subscription.Webhook object to the PATCH Accept Quote body. The subscription covers the entire lifecycle of the quote — you do not need to re-subscribe for each status. Update or pause delivery mid-flow by PATCHing again with only a Subscription object (omit Data).

PATCH /motor-insurance-quotes/{QuoteId} body (decoded)json

{
  "Data": {
    "PolicyStartDate": "2026-06-01"
  },
  "Subscription": {
    "Webhook": {
      "Url": "https://tpp.example.ae/webhooks/insurance-quote-events",
      "IsActive": true
    }
  }
}

04 Step 2

Receive and acknowledge the event

The Hub POSTs the event to your Webhook.Url with Content-Type: application/jwe. Respond 202 Accepted with an empty body immediately — process the payload asynchronously.

HTTP responsehttp

HTTP/1.1 202 Accepted
x-fapi-interaction-id: <echo the received value>

Warning

Failure to respond with 202 promptly may cause the Hub to retry delivery. Treat events as idempotent — the same event may arrive more than once.

05 Step 3

Decrypt the JWE and verify the inner JWS

The event is a JWE compact serialisation encrypted with your registered Encryption Certificate. The JWE header contains a kid that identifies which of your keys to use — decode the header first to select the correct private key, then decrypt.

See Receiving Event Notifications for the full FAPI-aligned guidance: key selection by kid, JWS signature verification, and required security checks.

06 Event Payload — Meta

Envelope metadata

Field	Type	Description
`EventDateTime`	string (date-time)	When the event was generated.
`EventResource`	string	The resource URI that triggered the event — e.g. `/motor-insurance-quotes/{QuoteId}`.
`EventType`	string	One of: `Resource.Created`, `Resource.Updated`, `Resource.Deleted`.
`QuoteId`	string (UUID)	The identifier of the quote the status change applies to.

07 Event Payload — Data

One of three event shapes per QuoteStatus

The Data object conforms to one of three schemas drawn from AEInsurance.AEInsuranceEvent:

Pending Completion Status — QuoteStatus is one of ApplicationPending, ApplicationApproved, PaymentRequired, PolicyIssued. May include BrokerInstructions[] (typically a payment URL) and Documents[] (on PolicyIssued in TPP-Led mode).
Completed Status — QuoteStatus: Completed. Carries the finalised Premium, PolicyTerm, CustomerPaidInFull, PolicyCountrySubDivision, and (where applicable) the Commission due to the TPP.
Terminal Status — QuoteStatus is one of Expired, Rejected, CustomerCancelled, LFICancelled. May include a Reason string.

The full schema is documented in Insurance Quotation API Guide — Event Schema and surfaced as an OpenAPI viewer in Insurance Quote Status Change Event.

08 Example

Decrypted Pending Completion event (ApplicationApproved)

Decrypted JWS payloadjson

{
  "iss": "https://auth1.[LFICODE].apihub.openfinance.ae",
  "aud": "[CLIENT_ID]",
  "iat": 1713196200,
  "exp": 1713199800,
  "message": {
    "Meta": {
      "EventDateTime": "2026-04-18T10:32:00Z",
      "EventResource": "/motor-insurance-quotes/8a4f2d09-2c5b-4f88-b1b3-1f06f7e91a2e",
      "EventType": "Resource.Updated",
      "QuoteId": "8a4f2d09-2c5b-4f88-b1b3-1f06f7e91a2e"
    },
    "Data": {
      "QuoteStatus": "ApplicationApproved",
      "BrokerInstructions": [
        {
          "ActionRequired": "Customer must complete premium payment at the LFI-hosted page.",
          "Url": "https://pay.examplelfi.ae/checkout/sess-c93e1f4a"
        }
      ]
    }
  }
}

09 Example

Decrypted Completed Status event

Decrypted JWS payloadjson

{
  "iss": "https://auth1.[LFICODE].apihub.openfinance.ae",
  "aud": "[CLIENT_ID]",
  "iat": 1713200000,
  "exp": 1713203600,
  "message": {
    "Meta": {
      "EventDateTime": "2026-04-18T11:00:00Z",
      "EventResource": "/motor-insurance-quotes/8a4f2d09-2c5b-4f88-b1b3-1f06f7e91a2e",
      "EventType": "Resource.Updated",
      "QuoteId": "8a4f2d09-2c5b-4f88-b1b3-1f06f7e91a2e"
    },
    "Data": {
      "QuoteStatus": "Completed",
      "PolicyStartDate": "2026-06-01",
      "PolicyEndDate": "2027-05-31",
      "PolicyTerm": "P1Y",
      "Premium": {
        "OneYearPremiumExcludingVAT": { "Currency": "AED", "Amount": "950.00" },
        "VATAmount": { "Currency": "AED", "Amount": "47.50" },
        "TotalOneYearPremium": { "Currency": "AED", "Amount": "997.50" }
      },
      "CustomerPaidInFull": true,
      "PolicyCountrySubDivision": "Dubai",
      "Commission": {
        "CommissionAmount": { "Currency": "AED", "Amount": "47.00" },
        "PaymentMethod": "ThroughAPIHub"
      }
    }
  }
}

10 Example

Decrypted Terminal Status event

Decrypted JWS payloadjson

{
  "iss": "https://auth1.[LFICODE].apihub.openfinance.ae",
  "aud": "[CLIENT_ID]",
  "iat": 1713204000,
  "exp": 1713207600,
  "message": {
    "Meta": {
      "EventDateTime": "2026-04-18T12:00:00Z",
      "EventResource": "/motor-insurance-quotes/8a4f2d09-2c5b-4f88-b1b3-1f06f7e91a2e",
      "EventType": "Resource.Updated",
      "QuoteId": "8a4f2d09-2c5b-4f88-b1b3-1f06f7e91a2e"
    },
    "Data": {
      "QuoteStatus": "CustomerCancelled",
      "Reason": "Customer declined payment at the LFI checkout."
    }
  }
}