The Webhook Notification API enables insurance providers and integration partners to notify Qoala whenever the status of a policy or claim transaction changes.

Typical use cases include policy issuance, policy activation, claim status updates, or the availability of supporting documents. Each webhook request contains the latest transaction status along with any related documents that Qoala requires to continue processing the transaction.

📘
Use this endpoint to send policy or claim status updates from your system to Qoala.

Webhook URL

POST {base_url}/api/integration/partner/webhook

Environment	Base URL
Staging	https://api-staging.qoala.app
UAT	https://api.uat.qoala.app
Production	https://api.qoala.app

API credentials will be provided during the integration onboarding process.

Authentication

All webhook requests must include a valid API key in the x-api-key request header.

The API key identifies the calling partner and is used for authentication. Partner information does not need to be included in the request body.

Example

x-api-key: {your-api-key}

Webhook Request

Example Request

curl --location 'https://api.qoala.app/api/integration/partner/webhook' \
--header 'x-api-key: {your-api-key}' \
--header 'Content-Type: application/json' \
--data '{
  "request_id": "QS-260715-I23KFR3M",
  "transaction_number": "PVI-001-TEST3",
  "transaction_type": "POLICY",
  "status": "POLICY_ACTIVE",
  "documents": [
    {
      "type": "POLICY_CERTIFICATE",
      "filename": "policy-certificate.pdf",
      "url": "https://www.example.com/policy-certificate.pdf"
    }
  ]
}'

Request Headers

Header	Required	Description
`x-api-key`	Yes	API key issued by Qoala
`Content-Type`	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description
`request_id`	string	No	Unique idempotency key used to safely retry webhook deliveries without creating duplicate processing.
`transaction_number`	string	Yes	Unique transaction identifier for the policy or claim.
`transaction_type`	string	Yes	Transaction category. Supported values: `POLICY` or `CLAIM` (case-insensitive).
`status`	string	Yes	Current transaction status. Refer to the Policy Status or Claim Status documentation for supported values.
`documents`	array	Yes	Collection of related documents. At least one document must be provided.

Documents

Field	Type	Required	Description
`type`	string	Yes	Type of document being submitted (for example, `POLICY_CERTIFICATE` or `CLAIM_DOCUMENTS`).
`url`	string	Yes	Publicly accessible URL where Qoala can retrieve the document.
`filename`	string	No	Original document filename.

Webhook Response

Qoala returns an HTTP response to acknowledge receipt of the webhook request.

A successful response confirms that the webhook has been received and processed successfully. It does not necessarily indicate that the underlying business process (such as policy issuance or claim approval) has been completed.

Success Response

{
  "status": "success",
  "data": {
    "request_id": "QS-260715-I23KFR3M",
    "transaction_number": "PVI-001-TEST3",
    "transaction_type": "POLICY",
    "journey_status": "WEBHOOK_RECEIVED",
    "status": "COMPLETED"
  },
  "message": "partner webhook processed successfully",
  "code": 200,
  "request_id": "QS-260715-I23KFR3M"
}

Success Notes

HTTP 200 OK indicates that the webhook has been successfully received and processed.
journey_status indicates the processing stage within Qoala.
data.status indicates the processing result and can be either:
- COMPLETED
- FAILED

Error Response

{
  "status": "failed",
  "data": null,
  "message": "transaction_number is required",
  "code": 400,
  "error_code": "INVALID_PAYLOAD_VALIDATION_ERR"
}

HTTP Status	Error Code	Description
400	`INVALID_PAYLOAD_VALIDATION_ERR`	The request payload is missing required fields or contains invalid values.
401	`INVALID_API_KEY_ERR`	The API key is missing or invalid.
409	—	The supplied `request_id` has already been used with a different request payload.
500	—	An unexpected server error occurred while processing the request.

Partners should retry webhook delivery for any response other than HTTP 200, unless the response is 409 Conflict, which indicates an idempotency violation that requires investigation rather than retrying.

Idempotency

To prevent duplicate processing, Qoala recommends including a unique request_id with every webhook request.

When retrying the same webhook, reuse the original request_id.

Scenario	Result
Same `request_id` and identical payload after successful processing	200 OK — Returns the previously processed response without reprocessing the request.
Same `request_id` with a different payload	409 Conflict — The request is rejected because the payload differs from the original request.
Request without `request_id`	Each request is treated as a new webhook and processed independently.