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

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

Response

200 OK

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

Error Codes

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"
  }'