Setting Up Webhooks

Webhooks let Helmdesk push real-time event notifications to your server. Instead of polling the API for changes, your application receives an HTTP POST request the moment something happens — a ticket is created, a reply is added, a status changes.

How Webhooks Work

You register a URL in your project's webhook settings

You select which events to listen for

When a matching event occurs, Helmdesk sends an HTTP POST to your URL

Your server processes the payload and returns a 2xx response

Creating a Webhook

Navigate to your project in the dashboard

Go to Settings > Webhooks in the sidebar

Click Create Webhook

Enter your endpoint URL (must be HTTPS in production)

Select the events you want to receive

Click Create

After creation, Helmdesk generates a signing secret for your webhook. Copy and store it securely — you will use it to verify that incoming requests are genuinely from Helmdesk.

Supported Events

Helmdesk can notify your server about the following events:

Ticket Events

ticket.created — A new ticket is submitted (via dashboard, API, widget, or email)

ticket.updated — A ticket's status, priority, or assignee changes

ticket.replied — A new reply is added to a ticket (staff or customer)

ticket.closed — A ticket is marked as closed

ticket.reopened — A closed ticket is reopened

ticket.deleted — A ticket is permanently deleted

Email Events

email.received — An inbound email is received and processed

email.sent — A transactional email is sent successfully

email.bounced — An email bounces (hard or soft)

email.complained — A recipient marks an email as spam

Article Events

article.published — A knowledge base article is published

article.updated — A published article is modified

Payload Format

Every webhook delivery is an HTTP POST with a JSON body. The structure is consistent across all event types:

{
  "event": "ticket.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "projectId": "60bf071a-927c-4c38-81d2-f0221fe138e4",
  "data": {
    "id": "ticket-uuid",
    "subject": "Cannot reset password",
    "status": "open",
    "priority": "high",
    "customerEmail": "user@example.com",
    "customerName": "Jane Doe",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

The data field contains the full resource object relevant to the event. For ticket events, it includes the ticket. For email events, it includes the email log entry.

Verifying Webhook Signatures

Every webhook request includes an x-helmdesk-signature header. Use this to verify the request came from Helmdesk and was not tampered with.

The signature is an HMAC-SHA256 hash of the raw request body, using your webhook's signing secret as the key.

import crypto from 'crypto'

function verifyWebhookSignature(
  body: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Always verify signatures before processing webhook payloads. Reject any request where the signature does not match.

Retry Policy

If your endpoint returns a non-2xx status code or does not respond within 10 seconds, Helmdesk retries the delivery:

Retry 1: 1 minute after the initial attempt

Retry 2: 5 minutes after retry 1

Retry 3: 30 minutes after retry 2

Retry 4: 2 hours after retry 3

Retry 5: 12 hours after retry 4

After 5 failed retries, the delivery is marked as failed. You can view failed deliveries in the webhook settings page and manually retry them.

If your endpoint fails consistently (10 consecutive failures), the webhook is automatically disabled. You will receive an email notification when this happens.

Best Practices

Respond quickly. Return a 200 status code as soon as you receive the payload. Process the data asynchronously if your logic takes time.

Handle duplicates. In rare cases, the same event may be delivered more than once. Use the event ID and timestamp to deduplicate.

Verify signatures. Always validate the x-helmdesk-signature header before trusting the payload.

Use HTTPS. Production webhook endpoints must use HTTPS to protect the payload in transit.

Log deliveries. Keep a log of received webhooks for debugging. Helmdesk also logs deliveries on its end — check the webhook detail page for delivery history.

Monitor failures. Set up alerts if your webhook endpoint starts failing. Consistent failures will disable the webhook automatically.

Common Use Cases

Slack notifications: Post a message to a Slack channel when a new ticket is created or a high-priority ticket is updated

CRM sync: Update customer records in your CRM when ticket status changes

Analytics: Track ticket volume, response times, and resolution rates in your own analytics pipeline

Escalation: Trigger PagerDuty or Opsgenie alerts for urgent tickets

Custom workflows: Automatically assign tickets, send follow-up emails, or update external systems based on ticket events

Testing Webhooks

During development, use a tool like ngrok to expose your local server to the internet:

ngrok http 3000

Use the ngrok URL as your webhook endpoint while developing. Switch to your production URL before going live.

You can also use the Test button on the webhook settings page to send a sample event to your endpoint without waiting for a real event to occur.