Webhooks

Webhooks send real-time HTTP POST notifications to your endpoint when events occur in Reechdesk. Instead of polling the API, your server receives event payloads as they happen.

How Webhooks Work

1. Create a webhook in the dashboard or via the API, specifying your endpoint URL and the events you want to subscribe to.
2. When a subscribed event occurs (e.g., a ticket is created), Reechdesk sends an HTTP POST request to your URL with the event payload.
3. Your server processes the payload and returns a 2xx status code to acknowledge receipt.
4. If your server returns a non-2xx status or times out (10 seconds), Reechdesk retries with exponential backoff.

Available Events

Request Format

Each webhook delivery sends an HTTP POST request with the following headers:

Payload Structure

{
  "event": "ticket.created",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "id": "clt_abc123",
    "ticketNumber": "TKT-0001",
    "subject": "Login issue",
    "status": "OPEN",
    "priority": "HIGH",
    "entityId": "ent_xyz789",
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Signature Verification

Each delivery includes an HMAC-SHA256 signature in the X-Reechdesk-Signature header. Always verify this signature to ensure the payload was sent by Reechdesk and not tampered with.

Node.js

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your route handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-reechdesk-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    'whsec_your_secret_here'
  );
  if (!isValid) return res.status(401).send('Invalid signature');
  // Process the event...
  res.status(200).send('OK');
});

Python

import hmac
import hashlib

def verify_signature(payload_bytes, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Policy

If your endpoint returns a non-2xx status or the request times out (10 seconds), Reechdesk retries with exponential backoff:

After 4 failed attempts, the delivery is marked as failed and no more retries are attempted.

Creating Webhooks

curl -X POST https://api.reechdesk.com/api/v1/company/webhooks \
  -H "X-API-Key: rd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Notifications",
    "url": "https://your-server.com/webhook",
    "events": ["ticket.created", "ticket.resolved"]
  }'

Best Practices

• Always verify the HMAC signature before processing a webhook payload.
• Process webhooks asynchronously — return a 2xx response immediately and handle the event in a background job.
• Use idempotency keys (the X-Reechdesk-Delivery header) to avoid processing duplicate deliveries.
• Implement proper error handling and logging for webhook processing.
• Keep your webhook endpoint secure and accessible only from the internet.