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_CANCELLED` last policy status
documents	Array	No	Policy documents like e-certificate and policy wording

Example Request Body

Purpose

{
  "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": "{base_url}/api/v2/policies/documents/policy_certificate.pdf"
        },
        {
          "type": "POLICY_WORDING",
          "filename": "Qoala-Gadget-Protection-Terms-Conditions.pdf",
          "alias": "policy_wording.pdf",
          "url": "{base_url}/api/v2/policies/documents/policy_wording.pdf"
        }
      ]
    }
  ]
}

Gadget

The insureds structure differs depending on product.parent_category. The example below is for the Gadget category.

{
  "transaction_number": "2607/3/PS00896",
  "partner_transaction_number": "2607/3/PS00896",
  "quotation_number": "QS-260716-AOR5F714",
  "policy_number": "G-ADLD-PARTNER-003-20260716-INQ4M",
  "insurance_number": "",
  "status": "POLICY_ACTIVE",
  "product_code": "G-ADLD-PARTNER-003",
  "start_protection_at": "2026-07-15T17:00:00+07:00",
  "end_protection_at": "2028-07-15T16:59:59+07:00",
  "purchased_at": "2026-07-16T06:02:08+07:00",
  "activated_at": "2026-07-16T06:02:09+07:00",
  "currency_code": "IDR",
  "payer_type": "CUSTOMER",
  "calculation": {
    "gwp": 3270000,
    "total_sum_insured": 30000000
  },
  "policy_holder": {
    "full_name": "John Doe",
    "email": "[email protected]",
    "phone_number": "+6281234567890"
  },
  "insureds": [
    {
      "uuid": "a36897f9-398c-40fe-896f-44d21f94e1eb",
      "type": "AGENT",
      "detail": {
        "covered_type_max": 24,
        "covered_type_unit": "MONTHS",
        "device_price": 0,
        "email": "[email protected]",
        "full_name": "John Doe ServiceAgent",
        "phone_number": "+6281234567891",
        "store_name": "Agent Bekasi",
        "sum_insured_formatted": "Rp0"
      },
      "documents": []
    },
    {
      "uuid": "c0a98cda-1cb6-4924-92bc-fe5b72b11874",
      "type": "GADGET",
      "detail": {
        "brand": "APPLE",
        "covered_type_max": 24,
        "covered_type_unit": "MONTHS",
        "device_category": "SMARTPHONE",
        "device_price": 30000000,
        "identity_number": "84373845292602252",
        "identity_type": "IMEI",
        "manufacturer": "APPLE",
        "model": "iPhone 17 Pro Max - 2TB",
        "series": "",
        "sum_insured": 30000000
      },
      "documents": [
        {
          "filename": "IMEI_PHOTO.png",
          "type": "IMEI_PHOTO",
          "url": "{base_url}/api/v2/policies/documents/IMEI_PHOTO.png"
        }
      ]
    }
  ],
  "product": {
    "country": "ID",
    "parent_category": "GADGET",
    "product_category": "ADLD",
    "product_summary": "",
    "code": "G-ADLD-PARTNER-003",
    "name": "Qoala Accidental Damage & Liquid Protection - 24 Months",
    "language": "en",
    "category_name": "Full Protection",
    "insurance_name": "Qoala",
    "partner_name": "ServiceAgent",
    "product_code": "G-ADLD-PARTNER-003",
    "product_name": "Qoala Accidental Damage & Liquid Protection - 24 Months",
    "product_description": "<p>[MSIG] Qoala Accidental Damage & Liquid Protection (ID) - 24 Months</p>",
    "product_terms": "<p>[MSIG] Qoala Accidental Damage & Liquid Protection (ID) - 24 Months</p>",
    "product_wording": "{base_url}/api/v2/policies/documents/Qoala-Gadget-Protection-Terms-Conditions.pdf",
    "claim_description": "",
    "timezone": "Asia/Jakarta",
    "terms": "",
    "riplay_document": "",
    "benefits": [
      {
        "code": "ADLD-MSIGVN-ALDI-IE1U0",
        "name": "Accidental Damage & Liquid Protection",
        "description": "Covers repair costs for physical damage to the purchased device that occurs in Indonesia during the protection period as a direct result of accidental damage or liquid damage.",
        "term": {
          "inclusion": [
            "Accidental damage that affects how your device works.",
            "Liquid damage that affects how your device works."
          ],
          "exclusion": [
            "Cosmetic damage: issues that only affect the device appearance, such as scratches, dents, or discoloration, without affecting device functionality.",
            "Non-accidental damage: issues caused by intentional misuse, wear and tear, or manufacturer defects.",
            "Loss/Theft: cases where your device is lost, stolen, or mysteriously missing."
          ]
        }
      }
    ]
  },
  "documents": [
    {
      "type": "POLICY_CERTIFICATE",
      "filename": "G-ADLD-PARTNER-003-20260716-INQ4M.pdf",
      "alias": "policy_certificate.pdf",
      "url": "{base_url}/api/v2/policies/documents/policy_certificate.pdf"
    },
    {
      "type": "POLICY_WORDING",
      "filename": "Qoala-Gadget-Protection-Terms-Conditions.pdf",
      "alias": "policy_wording.pdf",
      "url": "{base_url}/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.