Subscribe to UW Task Events

Registers a callback URL (webhook) to receive real-time event notifications whenever underwriting task activity occurs — such as a new task being created, a task status changing, or a task being assigned to a reviewer. The subscription applies across all merchants and is maintained until explicitly removed via POST /api/v1/uwTasks/unsubscribe.

Endpoint

POST /api/v1/uwTasks/subscribe

Authentication

Basic HTTP Authentication required. Encode username:password in Base64 and pass in the Authorization header:

Authorization: Basic {base64(username:password)}

When to use

Use this endpoint during initial integration setup to enable push-based notifications for UW task events instead of polling. Once subscribed, your callbackUrl will receive POST requests from Netevia HQ whenever a UW task event fires, eliminating the need to continuously poll GET /api/v1/uwTasks/getByMerchantId. This is especially valuable for high-volume ISOs managing many merchants in the underwriting pipeline simultaneously.

Request Body

Field	Type	Required	Description
callbackUrl	string	Yes	The publicly accessible HTTPS URL that will receive UW task event webhook payloads

{
  "callbackUrl": "https://portal.example-iso.com/webhooks/uw-task-events"
}

Response

200 OK

Field	Type	Description
status	string (enum)	HTTP status name, e.g., `"OK"`
error	string	Error message if the subscription failed
warning	string	Non-fatal warning message
validationResults	array	Field-level validation errors, if any
requestId	integer	Unique identifier for this API request

{
  "status": "OK",
  "error": null,
  "warning": null,
  "validationResults": [],
  "requestId": 88905
}

Error Codes

Code	When it happens
400	`callbackUrl` is missing, not a valid URL, or not reachable
401	Invalid or missing Basic Auth credentials
403	User does not have permission for this operation
500	Internal server error

Common Mistakes

Providing a callbackUrl that is not publicly accessible (e.g., localhost or an internal IP) — the Netevia HQ server must be able to reach this URL.
Subscribing multiple times without unsubscribing first — check whether a subscription already exists before calling this endpoint again to avoid duplicate webhook deliveries.
Not implementing an HTTPS endpoint on your server — the callback URL should use https:// to ensure secure delivery of event payloads.
Assuming the subscription is per-merchant — a single subscription receives events for all merchants under your account.

Related Endpoints

POST /api/v1/uwTasks/unsubscribe — remove the existing webhook subscription
GET /api/v1/uwTasks/getByMerchantId — poll for UW task data without a webhook (alternative to subscribing)
GET /api/v1/uwTasks/ticket/getCommentsByTicketId — fetch comments if you receive a task update event notification

Example

curl -X POST https://hq.staging.netevia.dev/api/v1/uwTasks/subscribe \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://portal.example-iso.com/webhooks/uw-task-events"
  }'

200OK