Webhooks

Webhooks allow you to receive real-time notifications when events occur in Support Station. This enables you to build integrations that respond to ticket updates, new messages, and more.

Webhooks are coming soon! This page describes the planned webhook functionality. Sign up for updates to be notified when webhooks are available.

How Webhooks Work

When you register a webhook, Support Station will send HTTP POST requests to your specified URL whenever subscribed events occur. Each request contains a JSON payload with event details.

Event Types

The following events will be supported:

Name
ticket.created
Description
A new ticket was created.
Name
ticket.updated
Description
A ticket was updated (status, priority, assignee, tags changed).
Name
ticket.message.created
Description
A new message was added to a ticket.
Name
customer.created
Description
A new customer was created.
Name
customer.updated
Description
A customer record was updated.

Webhook Payload

Each webhook request includes:

Name
id
Type
string
Description
Unique identifier for this webhook event.
Name
type
Type
string
Description
The event type that triggered the webhook.
Name
created_at
Type
timestamp
Description
When the event occurred.
Name
payload
Type
object
Description
The event data (varies by event type).

Example webhook payload

{
  "id": "evt_550e8400e29b41d4",
  "type": "ticket.created",
  "created_at": "2025-01-15T10:30:00.000Z",
  "payload": {
    "id": "ticket-uuid",
    "ticket_number": 42,
    "subject": "Help with login",
    "status": "OPEN",
    "priority": "MEDIUM",
    "channel": "API",
    "customer": {
      "id": "customer-uuid",
      "email": "john@example.com",
      "name": "John Doe"
    },
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}

Message Event Payload

When a new message is added to a ticket, the payload includes the message details along with ticket context.

ticket.message.created payload

{
  "id": "evt_abc123def456",
  "type": "ticket.message.created",
  "created_at": "2025-01-15T11:00:00.000Z",
  "payload": {
    "message": {
      "id": "message-uuid",
      "content": "Thanks for your help!",
      "type": "INBOUND",
      "author": {
        "type": "customer",
        "id": "customer-uuid",
        "email": "john@example.com",
        "name": "John Doe"
      },
      "created_at": "2025-01-15T11:00:00.000Z"
    },
    "ticket": {
      "id": "ticket-uuid",
      "ticket_number": 42,
      "subject": "Help with login",
      "status": "OPEN"
    }
  }
}

Verifying Webhooks

To ensure webhook requests are genuinely from Support Station, each request will include a signature header that you can verify:

X-SupportStation-Signature: sha256=abc123...

Verify the signature using your webhook secret:

Signature verification

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-supportstation-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  const event = req.body;
  console.log('Received event:', event.type);

  res.status(200).send('OK');
});

Best Practices

Respond quickly: Return a 2xx response within 5 seconds. Process webhooks asynchronously if needed.
Handle duplicates: Webhooks may be delivered more than once. Use the event id to deduplicate.
Verify signatures: Always verify the webhook signature before processing.
Retry handling: Failed webhooks will be retried with exponential backoff for up to 24 hours.

Registering Webhooks

When webhooks are available, you'll be able to register them in your dashboard settings under Webhooks:

Click "Add Webhook"
Enter your endpoint URL
Select the events you want to receive
Copy your webhook secret for signature verification
Test the webhook with a sample event

Support

Have questions about webhooks? Contact us at support@supportstation.io.