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: API Key, HMAC_SHA256, MD5, Bearer (JWT or static token), and Basic Auth. 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.

Authentication

Qoala authenticates every policy status notification using credentials and header names agreed during onboarding.

The examples below show the methods currently supported. Header names, message format, and encoding are partner-specific and will be confirmed during onboarding.

API Key

The shared API key is sent in a request header. Partner can verify the request by matching this value with the key exchanged during onboarding.

x-api-key: 6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39
Content-Type: application/json

HMAC_SHA256

Qoala signs the request with HMAC-SHA256 using a shared secret. A typical configuration generates a timestamp, serializes the mapped JSON body, then signs:

message = {apikey}|{timestamp}|{raw_json_body}
signature = Base64(HMAC-SHA256(secret, message))

The signature is computed after the request body is built, so it covers the exact JSON payload that is sent.

Example mapping

Body fields in this example are mapped as follows: status is sent as actual_status. Other fields keep the same name (policy_number, partner_transaction_number, quotation_number, product_code, start_protection_at, end_protection_at).

Example request

POST /api/notify/your/endpoint/callback
Content-Type: application/json
X-API-Key: INS_QL_12345678
X-Timestamp: 2026-07-16T10:00:00Z
X-Signature: YNlgRaQK5bh6aRpcMmPq33xBhq0uREkhQmE1yKDLF8I=

{
  "actual_status": "POLICY_ACTIVE",
  "end_protection_at": "2028-07-15T16:59:59+07:00",
  "partner_transaction_number": "TX-20260716-001",
  "policy_number": "G-ADLD-PARTNER-003-20260716-INQ4M",
  "product_code": "G-ADLD-PARTNER-003",
  "quotation_number": "QS-GADGET-20260716-ABC12",
  "start_protection_at": "2026-07-15T17:00:00+07:00"
}

The sample X-Signature above is produced with secret partner_hmac_secret over this concatenated message:

INS_QL_00000000|2026-07-16T10:00:00Z|{"actual_status":"POLICY_ACTIVE","end_protection_at":"2028-07-15T16:59:59+07:00","partner_transaction_number":"TX-20260716-001","policy_number":"G-ADLD-PARTNER-003-20260716-INQ4M","product_code":"G-ADLD-PARTNER-003","quotation_number":"QS-GADGET-20260716-ABC12","start_protection_at":"2026-07-15T17:00:00+07:00"}

How to verify

1. Read X-API-Key, X-Timestamp, and the raw request body (do not re-serialize the JSON).
2. Build message = X-API-Key + "|" + X-Timestamp + "|" + raw_body.
3. Compute Base64(HMAC-SHA256(shared_secret, message)).
4. Compare the result with X-Signature using a constant-time comparison.

MD5

Qoala can send an MD5 hex digest of a concatenated message. The digest may be placed in a header or in a body field (commonly Sign), depending on the partner contract. The digest is always a 32-character lowercase hex string.

signature = hex(MD5(format(params...)))

Example

If the agreed message is {secret}{start_date}{partner_transaction_number}:

secret = partner_md5_secret
message = partner_md5_secret2026-07-16TX-20260716-001
Sign    = f6656a796f452b4630ce9362ccafa59c

{
  "partner_transaction_number": "TX-20260716-001",
  "start_protection_at": "2026-07-16",
  "status": "POLICY_ACTIVE",
  "Sign": "f6656a796f452b4630ce9362ccafa59c"
}

Verify by rebuilding the same concatenated string from the received body (and shared secret) and comparing the MD5 hex digest.

Bearer

Qoala sends an Authorization: Bearer <token> header. The token can be:

• A static token exchanged during onboarding
• A JWT signed by Qoala (HS256, HS384, or HS512)
• A token fetched from the partner's auth endpoint (OAuth / REST) immediately before the callback

Static token

Authorization: Bearer partner_static_token
Content-Type: application/json

JWT

Qoala signs a JWT with the shared secret. Default claims:

Additional custom claims can be included when required.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Verify the JWT using the shared secret, signing method, and expected issuer QOALA.

Token from partner auth endpoint

If the partner requires Qoala to obtain a token first, Qoala calls the partner auth URL, reads the token from the response (for example access_token), prefixes it with Bearer , and sends it on the policy callback:

Authorization: Bearer {access_token_from_auth_response}
Content-Type: application/json

Basic Auth

Qoala sends HTTP Basic Authentication. Username and password are concatenated, Base64-encoded, and prefixed with Basic .

credential = Base64("USERNAME:{password}")
Authorization: Basic {credential}

Example

username:password = qoala:partner_password
Authorization: Basic cW9hbGE6cGFydG5lcl9wYXNzd29yZA==
Content-Type: application/json

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. Authentication headers depend on the method configured during onboarding. See Authentication.

Body

The following are the details of the request body of the webhook.

calculation

policy_holder

insureds

Each item in the insureds array represents an insured party. The detail object structure depends on type.

Supported type values: USER, AGENT, GADGET, TRAVEL, FLIGHT, VEHICLE, GOODS, PET, LOAN, SHIPPING, PACKAGE, EXPERIENCE, HOSPITALITY, USER_LENDER, USER_BORROWER, BENEFICIARY, OWNER

insureds[].detail (type = USER / USER_LENDER / USER_BORROWER / BENEFICIARY / OWNER)

insureds[].detail (type = AGENT)

insureds[].detail (type = GADGET)

insureds[].detail (type = VEHICLE)

insureds[].detail (type = TRAVEL / FLIGHT)

insureds[].detail (type = GOODS)

insureds[].detail (type = PET)

insureds[].detail (type = LOAN)

insureds[].detail (type = SENDER / RECIPIENT)

additional_data fields: city, country, zipcode, subject

insureds[].detail (type = SHIPPING)

insureds[].detail (type = PACKAGE)

insureds[].documents[]

product

product.benefits[]

documents

Example Request Body

Purpose (simplified async flow)

{
  "partner_transaction_number": "TX-20260716-001",
  "transaction_number": "QS-GADGET-20260716-ABC12",
  "product_code": "G-ADLD-PARTNER-003",
  "policies": [
    {
      "number": "G-ADLD-PARTNER-003-20260716-INQ4M",
      "status": "POLICY_ACTIVE",
      "start_protection_at": "2026-07-15T17:00:00+07:00",
      "end_protection_at": "2028-07-15T16:59:59+07:00",
      "premium_amount": 3270000,
      "documents": [
        {
          "type": "POLICY_CERTIFICATE",
          "filename": "G-ADLD-PARTNER-003-20260716-INQ4M.pdf",
          "alias": "policy_certificate.pdf",
          "url": "https://api.uat.qoala.app/api/v2/policies/documents/policy_certificate.pdf"
        },
        {
          "type": "POLICY_WORDING",
          "filename": "Qoala-Gadget-Protection-Terms-Conditions.pdf",
          "alias": "policy_wording.pdf",
          "url": "https://api.uat.qoala.app/api/v2/policies/documents/policy_wording.pdf"
        }
      ]
    }
  ]
}

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.