Receive webhooks

Webhooks tell your server when something changes, so you do not have to poll. Set them up before you go live: a delivered test event is one of the steps of the activation checklist.

1. Build a receiverlink

Add an HTTPS route on a public host that accepts a JSON POST. Read the raw body before parsing it: you need the exact bytes to verify the signature.

2. Register itlink

curl -X POST https://insure-api.netapps.ng/api/v1/webhook-endpoints \
  -H "x-api-key: $INSURETECH_API_KEY" \
  -H "Idempotency-Key: 5a7c9e1b-3d5f-4a8c-b2e4-6f8a0c2e4b6d" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://merchant.example.com/webhooks/insuretech",
    "events": ["*"],
    "description": "Order service"
  }'

A test key registers a test endpoint, which receives test events only. Register your endpoint again with your live key when you go live.

3. Verify every deliverylink

Compute the HMAC-SHA256 of <OIIS-Timestamp>.<OIIS-Event-Id>. followed by the raw body, keyed with the whole secret, and compare it with each v1= value in OIIS-Signature. Refuse a timestamp more than five minutes old. Webhooks has the full recipe, a Node.js function and a signed sample delivery to test against.

4. Send a test eventlink

curl -X POST https://insure-api.netapps.ng/api/v1/webhook-endpoints/{endpointId}/test \
  -H "x-api-key: $INSURETECH_API_KEY"

The answer shows what your endpoint replied. A 2xx from a test endpoint ticks the webhook step of the activation checklist.

5. Act on the eventslink

Event	What your app does
`quote.completed`	A pending quote has its price. Show it, and let your customer buy it.
`purchase.completed`	The policy was issued. Store `policyId` and send your customer their documents.
`purchase.failed`	The policy will never be issued. Refund your customer.
`policy.renewal_due`	Offer the renewal. Service the policy shows how.
`policy.cancelled`, `policy.lapsed`, `policy.expired`	Cover has ended. Update what your customer sees.
`policy.endorsement_applied`	A change to the policy took effect.
`document.ready`	A new document is ready to download.
`claim.updated`, `claim.settled`, `claim.rejected`	Tell your customer where their claim stands.

Answer quicklylink

Answer 2xx as soon as you have stored the event, then do the work.
A 5xx, 408, 425, 429 or network failure is retried with backoff. Any other status fails the delivery.
Use eventId to ignore a delivery you already handled: every attempt carries the same one.
Replay a failed delivery from the log with POST /webhooks/deliveries/{deliveryId}/retry.

Nextlink

Service the policy after the sale.