Subscribe to Ticket events

Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

Subscribe to Ticket Events

Registers a callback URL with Netevia HQ so that your system receives real-time HTTP POST notifications whenever a tracked event occurs on any ticket accessible to your account. Supported events include status changes, new comments, new attachments, and department transfers. The subscription is scoped to the authenticated user's account.

Endpoint

POST /api/v1/tickets/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 register a webhook endpoint on your platform. Once subscribed, you no longer need to poll getCommentsByTicketId or getTicketById for updates — Netevia HQ will push notifications to your callback URL automatically. This is especially useful for tracking Instant Funding ticket responses without continuous polling.

Request Body

Field	Type	Required	Description
`callbackUrl`	string	Yes	The publicly accessible HTTPS URL that will receive event POST requests from Netevia HQ.

{
  "callbackUrl": "https://yourplatform.com/webhooks/netevia/tickets"
}

Response

200 OK

Field	Type	Description
`requestId`	integer	Internal request tracking ID.
`success`	boolean	`true` if the subscription was registered successfully.
`error`	string	Error message if the subscription failed.
`validationErrors`	array	List of field-level validation issues.

{
  "requestId": 98132,
  "success": true,
  "error": null,
  "validationErrors": []
}

Callback Payload

When an event occurs, Netevia HQ sends an HTTP POST to your callbackUrl with the following JSON body:

Field	Type	Description
`CallbackUrl`	string	The URL registered for this subscription.
`TicketId`	string	The ID of the ticket that triggered the event.
`EventType`	string	The type of event that occurred (see Event Types table).
`MID`	string	Merchant ID associated with the ticket.
`Title`	string	Ticket subject/title.
`PreviousValue`	string	The previous value (for status change events).
`CurrentValue`	string	The new value or content (e.g., comment text, new status).

Callback Example:

{
  "CallbackUrl": "https://yourplatform.com/webhooks/netevia/tickets",
  "TicketId": "48291",
  "EventType": "Add Comment",
  "MID": "9180000000000000",
  "Title": "Instant Funding",
  "PreviousValue": "",
  "CurrentValue": "Please provide a voided check to complete the Instant Funding setup."
}

Event Types

Value	Name	Description
0	Add Attachment	A new file was attached to the ticket.
1	Add Comment	A new comment was posted to the ticket thread.
2	Change Status	The ticket status was updated (e.g., `New` to `InProgress`).
3	Change Department	The ticket was transferred to a different department.

Error Codes

Code	When it happens
400	`callbackUrl` is missing or not a valid URL format.
401	Invalid or missing Basic Auth credentials.
403	User does not have permission for this operation.
404	Ticket or resource not found.
500	Internal server error.

Common Mistakes

Registering an HTTP (non-HTTPS) callback URL — the server may reject insecure endpoints.
Not making the callback endpoint publicly accessible — Netevia HQ must be able to reach the URL from its servers.
Not handling duplicate event deliveries — implement idempotency in your callback handler using TicketId and EventType.
Subscribing multiple times with the same URL — call POST /api/v1/tickets/unsubscribe first to clear an existing subscription before re-registering.

Related Endpoints

POST /api/v1/tickets/unsubscribe — Remove the active webhook subscription.
GET /api/v1/tickets/getTicketById — Poll for ticket details if webhooks are not available.
GET /api/v1/tickets/getCommentsByTicketId — Retrieve comments if a callback is missed.

Example

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