Policy Webhooks
The milestones of the policy lifecycle are notified through webhooks of type insurance.policy.status_changed. Two statuses produce an event: issued (issuance confirmed by the insurer) and canceled (cancellation confirmed). The transient statuses (issuance_requested, cancellation_requested) and the natural end of term (finished) do not produce webhooks — the transient ones are the result of your own calls, and the end of term is known since issuance through term.end_date.
Receiving webhooks requires a configured callback URL. See Authentication — Receiving webhooks.
Webhook structure
| Field | Type | Description |
|---|---|---|
webhook_type | string | Always insurance.policy.status_changed. |
webhook_datetime | string | Date and time of the event in ISO 8601. |
data | object | Event data. See table below. |
Attributes of data
| Field | Type | Description |
|---|---|---|
policy_key | string | Policy key. |
order_key | string | Key of the order that originated the policy — the correlation with your sale. |
status | string | New status: issued or canceled. |
external_policy_number | string | Policy number at the insurer. Present in the issued event. |
reason | string | Cancellation reason. Present in the canceled event, when informed. |
{
"webhook_type": "insurance.policy.status_changed",
"webhook_datetime": "2026-07-16T15:00:00Z",
"data": {
"policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
"order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
"status": "status",
"external_policy_number": "APL-2026-000123",
"reason": null
}
}
Events per status
Policy issued
Sent when the insurer confirms the issuance. From this event on, the external_policy_number is available and coverage is formally in force. Since each policy is issued independently, an order with N products produces N events of this type — possibly at different moments.
{
"webhook_type": "insurance.policy.status_changed",
"webhook_datetime": "2026-07-16T15:00:00Z",
"data": {
"policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
"order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
"status": "issued",
"external_policy_number": "APL-2026-000123",
"reason": null
}
}
Policy canceled
Sent when the insurer confirms the cancellation — requested through the policy cancellation or through the post-emission order cancellation. The premium refund due (full within the cooling-off right, pro rata afterwards) is computed at this moment and executed by QI Tech.
{
"webhook_type": "insurance.policy.status_changed",
"webhook_datetime": "2026-08-02T09:30:00Z",
"data": {
"policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
"order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
"status": "canceled",
"external_policy_number": "APL-2026-000123",
"reason": "Customer requested cancellation"
}
}
QI Tech webhooks must not be mapped strictly. Additional fields may be added to the webhook payloads returned by our APIs.