Insurer API documentationv1 · draft

API reference

Webhook endpoints

Where Wathiqaty sends events (see the Webhooks guide for payloads and signatures). Up to 5 endpoints per environment.

Base URL https://sandbox-api.wathiqaty.com/api/v1 (sandbox) · https://api.wathiqaty.com/api/v1 (production)

List endpoints

GET/partner/webhook-endpoints

Scope: webhooks:manage

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-endpoints" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · Your endpoints.

{
  "status": "success",
  "data": [
    {
      "id": "f0e1d2c3-b4a5-4968-8776-655443322110",
      "url": "https://core.insurer.example/wathiqaty/webhooks",
      "events": [
        "policy.issued",
        "policy.cancelled",
        "cancellation.requested"
      ],
      "enabled": true,
      "description": "Core policy system",
      "createdAt": "2026-11-01T10:00:00.000Z"
    }
  ],
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Create an endpoint

POST/partner/webhook-endpoints

Scope: webhooks:manageIdempotency-Key optional

The response carries signingSecret once. Store it in your secret manager.

Body (JSON)

Name	Description
`url` stringrequired	Public `https://` URL. Private and loopback addresses are refused.
`events` string[]required	Event types, or `["*"]` for all, current and future.
`description` string	Up to 255 characters.

Errors

Status	Code	When
422	`validation_error`	Not https, a private address, or an unknown event type.
409	`webhook_endpoint_limit`	You already have 5 endpoints in this environment.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-endpoints" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://core.insurer.example/wathiqaty/webhooks","events":["policy.issued","policy.cancelled","cancellation.requested"],"description":"Core policy system"}'

201 · The endpoint and its signing secret.

{
  "status": "success",
  "data": {
    "id": "f0e1d2c3-b4a5-4968-8776-655443322110",
    "url": "https://core.insurer.example/wathiqaty/webhooks",
    "events": [
      "policy.issued",
      "policy.cancelled",
      "cancellation.requested"
    ],
    "enabled": true,
    "description": "Core policy system",
    "createdAt": "2026-11-01T10:00:00.000Z",
    "signingSecret": "whsec_5f3c9a…"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Update an endpoint

PATCH/partner/webhook-endpoints/{id}

Scope: webhooks:manage

Re-enabling an endpoint that was disabled after failures does not resend old events; redeliver them from the delivery list.

Path parameters

Name	Description
`id` uuidrequired	The endpoint's Wathiqaty id.

Body (JSON)

Name	Description
`url` string	New URL.
`events` string[]	Replaces the list.
`enabled` boolean	Pause or resume deliveries.
`description` string	Up to 255 characters.

Errors

Status	Code	When
404	`not_found`	Endpoint doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X PATCH "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-endpoints/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

200 · The endpoint.

{
  "status": "success",
  "data": {
    "id": "f0e1d2c3-b4a5-4968-8776-655443322110",
    "url": "https://core.insurer.example/wathiqaty/webhooks",
    "events": [
      "policy.issued",
      "policy.cancelled",
      "cancellation.requested"
    ],
    "enabled": false,
    "description": "Core policy system",
    "createdAt": "2026-11-01T10:00:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "PATCH",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Delete an endpoint

DELETE/partner/webhook-endpoints/{id}

Scope: webhooks:manage

Path parameters

Name	Description
`id` uuidrequired	The endpoint's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Endpoint doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X DELETE "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-endpoints/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

204 · Deleted. No body.

(no body)

Rotate the signing secret

POST/partner/webhook-endpoints/{id}/rotate-secret

Scope: webhooks:manage

For 24 hours every delivery carries two signatures (old and new), so you can deploy the new secret without dropping events.

Path parameters

Name	Description
`id` uuidrequired	The endpoint's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Endpoint doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-endpoints/{id}/rotate-secret" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · The new secret, shown once.

{
  "status": "success",
  "data": {
    "signingSecret": "whsec_a91e0b…",
    "previousSecretExpiresAt": "2026-11-06T09:15:02.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Send a test event

POST/partner/webhook-endpoints/{id}/test

Scope: webhooks:manage

Sends a signed ping event now and reports what your endpoint answered.

Path parameters

Name	Description
`id` uuidrequired	The endpoint's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Endpoint doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-endpoints/{id}/test" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · Your endpoint's answer.

{
  "status": "success",
  "data": {
    "deliveryId": "0d0a7c9b-8e6f-4a5b-9c3d-2e1f0a9b8c7d",
    "status": 200,
    "latencyMs": 182
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

List deliveries

GET/partner/webhook-endpoints/{id}/deliveries

Scope: webhooks:manage

The last 30 days of attempts, newest first.

Path parameters

Name	Description
`id` uuidrequired	The endpoint's Wathiqaty id.

Query parameters

Name	Description
`eventType` string	Only this event type.
`failed` boolean	Only attempts that didn't get a 2xx.
`page` integer	Page number, from 1. Default 1.
`size` integer	Items per page, 1–100. Default 20.
`sortOrder` string	Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed. One of: `asc`, `desc`

Errors

Status	Code	When
404	`not_found`	Endpoint doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-endpoints/{id}/deliveries" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · A page of delivery attempts.

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "0d0a7c9b-8e6f-4a5b-9c3d-2e1f0a9b8c7d",
        "eventId": "evt_7f6c1b0e-3c2d-4c84-9a0e-2f3b1c5d7e90",
        "eventType": "policy.issued",
        "attempt": 2,
        "status": 503,
        "latencyMs": 10000,
        "responseSnippet": "Service Unavailable",
        "nextAttemptAt": "2026-11-05T09:51:00.000Z",
        "createdAt": "2026-11-05T09:21:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "size": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Redeliver an event

POST/partner/webhook-deliveries/{id}/redeliver

Scope: webhooks:manage

Sends the event again now, with the same event id (so your dedupe still works).

Path parameters

Name	Description
`id` uuidrequired	The delivery's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Delivery doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/webhook-deliveries/{id}/redeliver" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

202 · Queued.

{
  "status": "success",
  "data": {
    "deliveryId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}