Webhooks

Webhooks let you receive real-time notifications when events occur in your NexaDesk workspace. NexaDesk sends HTTP POST requests to your configured URL whenever a subscribed event fires.

Setting Up Webhooks

1. Go to Settings > Webhooks in your NexaDesk dashboard
2. Click Add Webhook
3. Enter the Endpoint URL — the URL where NexaDesk will send POST requests
4. Select the events you want to subscribe to
5. Click Save

NexaDesk sends a test ping to your URL to verify it is reachable. Your endpoint must respond with a 200 status code.

Event Types

Payload Format

All webhook payloads follow this structure:

{
  "event": "lead.created",
  "timestamp": "2026-03-20T14:00:00.000Z",
  "workspace_id": "ws_xxxxxxxxxxxx",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "visitor_name": "John Doe",
    "visitor_email": "[email protected]",
    "pipeline_stage": "new",
    "source": "widget",
    "created_at": "2026-03-20T14:00:00.000Z"
  }
}

The data field contains the full resource object relevant to the event.

Signature Verification

Each webhook request includes a signature header for verifying authenticity:

X-NexaDesk-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The signature is an HMAC-SHA256 hash of the raw request body using your webhook secret as the key.

const crypto = require("crypto");

function verifyWebhook(body, signature, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret)
      .update(body, "utf-8")
      .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post("/webhooks/nexadesk", (req, res) => {
  const signature = req.headers["x-nexadesk-signature"];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.NEXADESK_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = req.body;
  // Process the event...

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

Retry Policy

If your endpoint does not respond with a 2xx status code, NexaDesk retries the delivery:

After 5 failed attempts, the webhook delivery is marked as failed. You can view failed deliveries and retry them manually from the webhook settings page.

Webhook Logs

View delivery history under Settings > Webhooks > [Webhook] > Logs. Each entry shows:

• Event type and timestamp
• HTTP status code from your endpoint
• Response time
• Request and response payloads (for debugging)

Best Practices

• Respond quickly — Return a 200 status code within 5 seconds. Process the event asynchronously if needed.
• Handle duplicates — In rare cases, an event may be delivered more than once. Use the event ID for idempotency.
• Verify signatures — Always verify the X-NexaDesk-Signature header to ensure the request is from NexaDesk.
• Use HTTPS — Webhook endpoints must use HTTPS in production.