Webhooks

Webhooks let your application receive real-time HTTP callbacks when events occur in Helpdesk. All webhook endpoints require admin permission.

The webhook object

Attribute	Type	Description
id	string	Unique identifier
name	string	Display name
targetUrl	string	HTTPS endpoint to receive events
events	array	List of subscribed event types
active	boolean	Whether the webhook is active
signingSecret	string	Signing secret (only returned on creation)
createdAt	string	Creation time (ISO 8601 UTC)
updatedAt	string	Last update time (ISO 8601 UTC)

Supported events

Event	Description
ticket.created	A new ticket is created
ticket.updated	A ticket is updated (status, priority, custom fields, etc.)
ticket.deleted	A ticket is deleted
ticket.assignment.changed	A ticket’s assignee changes
ticket.resolved	A ticket status changes to resolved

List webhooks

GET /helpdesk/api/v1/webhooks

Response

{
  "webhooks": [ ... ]
}

Retrieve a webhook

GET /helpdesk/api/v1/webhooks/:id

Create a webhook

POST /helpdesk/api/v1/webhooks

Request body

{
  "webhook": {
    "name": "My Integration",
    "targetUrl": "https://example.com/webhook",
    "events": ["ticket.created", "ticket.updated"],
    "active": true
  }
}

Field	Type	Required	Description
name	string	yes	Display name
targetUrl	string	yes	HTTPS endpoint URL
events	array	yes	Event types to subscribe to
active	boolean	no	Defaults to true

Response

Returns 201 Created. The signingSecret is included only in the creation response — store it securely.

{
  "webhook": {
    "id": "whk_abc123",
    "name": "My Integration",
    "targetUrl": "https://example.com/webhook",
    "events": ["ticket.created", "ticket.updated"],
    "active": true,
    "signingSecret": "whsec_...",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Update a webhook

PUT /helpdesk/api/v1/webhooks/:id

Request body

{
  "webhook": {
    "name": "Updated Name",
    "events": ["ticket.created"],
    "active": false
  }
}

All fields are optional. Only provided fields are updated.

Delete a webhook

DELETE /helpdesk/api/v1/webhooks/:id

Returns 204 No Content.

Webhook payloads

When an event fires, Helpdesk sends a POST request to your targetUrl with a JSON payload:

{
  "event": "ticket.created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "ticket": { ... }
  }
}

For ticket.updated, the payload includes only the changed fields:

{
  "event": "ticket.updated",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "ticket": {
      "id": "tkt_abc123",
      "updatedFields": {
        "status": { "from": "open", "to": "pending" }
      }
    }
  }
}