Policy callback API is provided by the partner and is the way Qoala shares the latest status of the transaction. Through this callback API, Qoala will share policy information based on each transaction, such as policy_number, policy_status, and a link to the e-certificate. Qoala's system supports several methods of authorization, including HMAC_SHA256, MD5, Bearer, Basic Auth, etc. Qoala can support a new method of authorization if needed.
Callback URL
Each partner can configure a callback URL for policy creation webhook.
POST {partner-url-path}
partner-url-path = URL from partner to receive webhook notification
The configuration can be done through at the time of onboarding.
Webhook Signature
Partners can optionally verify the authenticity of notifications sent by Qoala by the header x-api-key
Example:
x-api-key: 6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39
Webhook Request
Each time a status is updated then a request with the following details will be made against the specified Callback URL [partner-url-path]
Headers
The following are the details of the request headers of the webhook
| Header | Expected Value |
|---|---|
| x-api-key | Refer to Signature section |
| Content-Type | application/json |
Body
The following are the details of the request body of the webhook
| Object Fields | Type | Required | Description |
|---|---|---|---|
| policy_number | string | Yes | policy number generated by qoala |
| partner_transaction_number | string | No | The Transaction ID serves as a unique identifier for each transaction initiated through the API. Partners are responsible for generating this ID and ensuring its uniqueness across their transactions. |
| product_code | string | No | Defined by Qoala, plays a pivotal role in the API, providing contextual information about certain aspects of the product. However, as of now, the details for this field will be shared at a later stage when the product is ready for testing. |
| quotation_number | string | No | Unique quotation number generated by qoala system |
| status | string | Yes | Enum: POLICY_ACTIVE, POLICY_ISSUING, POLICY_CANCELLEDlast policy status |
| documents | Array | No | Policy documents like e-certificate and policy wording |
Webhook Response
HTTP response status code from partner will be tracked and
- HTTP status code 200 will be acknowledged by Qoala as notification successfully received. No retry will be done.
- Other HTTP status code will be marked as failed and will be retried. Request will be retried up to 8 times with exponential backoff interval.