GudDesk
Docs
Webhooks

Webhooks

Receive real-time event notifications from GudDesk via webhooks.

Webhooks let you receive HTTP POST notifications when events happen in your GudDesk workspace. Use them to sync data, trigger workflows, or power AI agents.

Setting Up Webhooks

Via Dashboard

  1. Go to Workspace Settings > Webhooks
  2. Click Add Endpoint
  3. Enter your webhook URL
  4. Select the events you want to receive
  5. Copy the signing secret for signature verification

Via API (Agent Auto-Registration)

AI agents can programmatically register webhooks using the API:

curl -X POST https://guddesk.com/api/agent/webhooks \
  -H "Authorization: Bearer gd_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.com/webhook",
    "events": {
      "onMessageCreated": true,
      "onConversationCreated": true
    }
  }'

The response includes the signing secret. If a webhook with the same URL already exists, the existing endpoint is returned.

Event Types

EventFieldDescription
Message CreatedonMessageCreatedA new message was sent (visitor, agent, or bot)
Conversation CreatedonConversationCreatedA new conversation was started
Conversation ClosedonConversationClosedA conversation was closed
Conversation AssignedonConversationAssignedA conversation was assigned to an agent

Verifying Signatures

Every webhook request includes an HMAC SHA-256 signature in the X-GudDesk-Signature header for verification:

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

Verify the signature using your webhook secret:

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.

Testing Webhooks

For local development, use a tunneling service like ngrok:

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

When running GudDesk locally (localhost:3000) and your agent locally (localhost:3001), you can register webhooks with HTTP URLs — no HTTPS required for local development.

Best Practices

  • Respond quickly — Return a 200 status within 5 seconds. Do heavy processing asynchronously.
  • Verify signatures — Always validate the X-GudDesk-Signature header in production.
  • Graceful shutdown — If your agent registered a webhook programmatically, unregister it on shutdown via DELETE /api/agent/webhooks.
API OverviewSlack