Webhooks

Webhooks let you receive HTTP POST notifications when events happen in your GudDesk workspace. Use them to sync data, trigger workflows, or integrate with external tools.

Setting Up Webhooks

1. Go to Dashboard > Settings > Webhooks
2. Click Add Endpoint
3. Enter your webhook URL (must be HTTPS)
4. Select the events you want to receive
5. Click Save

GudDesk will send a test event to verify your endpoint is reachable.

Event Types

Payload Format

All webhook payloads follow this structure:

{
  "id": "evt_abc123",
  "type": "conversation.created",
  "createdAt": "2025-06-15T10:30:00Z",
  "data": {
    "id": "conv_xyz789",
    "status": "open",
    "customer": {
      "id": "cus_123",
      "email": "jane@example.com",
      "name": "Jane Doe"
    },
    "messages": [
      {
        "id": "msg_001",
        "role": "customer",
        "text": "Hi, I need help with my account",
        "createdAt": "2025-06-15T10:30:00Z"
      }
    ]
  }
}

Verifying Signatures

Every webhook request includes a signature header for verification:

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

Verify the signature using your webhook secret (found in Settings):

import crypto from "crypto";
 
function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

Always verify signatures in production to ensure requests are genuinely from GudDesk.

Retry Policy

If your endpoint returns a non-2xx status code, GudDesk retries with exponential backoff:

After 5 failed attempts, the event is marked as failed and can be manually retried from the dashboard.

Testing Webhooks

Use the Test button in Settings to send a sample event to your endpoint. For local development, use a tunneling service like ngrok:

ngrok http 3000
# Use the ngrok URL as your webhook endpoint

Best Practices

• Respond quickly — Return a 200 status within 5 seconds. Do heavy processing asynchronously.
• Handle duplicates — Use the id field to deduplicate events.
• Verify signatures — Always validate the X-GudDesk-Signature header.
• Use HTTPS — Webhook URLs must use HTTPS in production.