Webhooks Setup

Webhooks send real-time notifications to your systems when events happen in Support Station. Use them to integrate with CRMs, notification systems, data warehouses, and custom applications.

What Are Webhooks?

Webhooks are HTTP callbacks that send data to your URL when specific events occur. Instead of polling Support Station for changes, your system receives instant notifications.

Example: When a ticket is created, Support Station sends a POST request to your URL with ticket details.

Plan Requirements

Webhooks are available on Standard plans and above.

Plan	Webhooks
Free	✗
Starter	✗
Standard	10 webhooks
Pro	Unlimited
Enterprise	Unlimited

Setting Up a Webhook

Step 1: Access Webhook Settings

Go to Settings > Webhooks
Click Create Webhook

Step 2: Configure the Webhook

Field	Description
Name	Descriptive name (e.g., "CRM Sync")
URL	Your endpoint that receives webhook data
Events	Which events trigger this webhook
Active	Enable/disable the webhook

Step 3: Select Events

Choose which events trigger the webhook:

Event	When It Fires
`ticket.created`	New ticket created
`ticket.updated`	Ticket status, priority, assignment, or tags changed
`message.created`	New customer-visible message added to ticket

Note: Internal notes do not trigger the message.created event.

Select multiple events for one webhook or create separate webhooks for different event types.

Step 4: Test the Webhook

Click Send Test in webhook settings
A sample payload is sent to your URL
Verify your system receives it
Check the response status (should be 200 OK)

Webhook Payload

Webhooks send JSON payloads with event data.

Sample Payload: ticket.created

{
  "event": "ticket.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "ticket": {
      "id": "tkt_abc123",
      "subject": "Can't log in",
      "status": "OPEN",
      "priority": "MEDIUM",
      "customer": {
        "id": "cust_xyz789",
        "email": "john@example.com",
        "name": "John Doe"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Sample Payload: message.created

{
  "event": "message.created",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "ticket": {
      "id": "tkt_abc123",
      "subject": "Can't log in"
    },
    "message": {
      "id": "msg_def456",
      "content": "I've tried resetting my password but...",
      "type": "INBOUND",
      "createdAt": "2024-01-15T11:00:00Z"
    }
  }
}

Webhook Security

HMAC Signature

Every webhook includes a signature header for verification:

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

Verify the signature to ensure the webhook is from Support Station:

const crypto = require('crypto');

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

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

Your webhook secret is shown in the webhook settings when you create it.

HTTPS Required

Webhook URLs must use HTTPS for security. HTTP URLs are not accepted.

Delivery and Retries

Successful Delivery

A webhook is successful when your endpoint returns:

HTTP 200 OK
HTTP 201 Created
HTTP 202 Accepted

Retry Policy

If delivery fails, Support Station retries up to 5 times with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	15 minutes
5	30 minutes

After 5 failed attempts, the webhook delivery is marked as failed for that event.

Timeout

Your endpoint should respond within 10 seconds. Longer responses may timeout.

Tip: Accept the webhook quickly (return 200 OK) and process asynchronously.

Circuit Breaker

If a webhook fails 10 consecutive times, it's automatically disabled to prevent continued failures. You'll receive a notification and can re-enable it after fixing the issue.

Monitoring Webhooks

Delivery History

View recent deliveries for each webhook:

Go to Settings > Webhooks
Click on a webhook
View Delivery History

Each delivery shows:

Timestamp
Event type
Response status code
Response time
Error message (if failed)

Failed Deliveries

Review failed webhooks to identify issues:

Check response codes (4xx = client error, 5xx = server error)
View error messages
Identify patterns

Best Practices

Respond Quickly

Return 200 OK immediately, process later:

app.post('/webhook', (req, res) => {
  res.status(200).send('OK');

  // Process asynchronously
  processWebhook(req.body);
});

Handle Duplicates

Webhooks may occasionally be sent twice. Make your handler idempotent:

async function handleTicketCreated(ticket) {
  const existing = await db.findByTicketId(ticket.id);
  if (existing) return; // Already processed

  await db.insert(ticket);
}

Log Everything

Keep logs for debugging:

Incoming payloads
Processing results
Errors and exceptions

Monitor Health

Set up alerting for:

Webhook failures
High response times
Unexpected error rates

Troubleshooting

Webhook Not Firing

Check:

Webhook is active (enabled)
Event type is selected
URL is correct and accessible
Event actually occurred in Support Station

Signature Verification Failing