Webhooks

Receive real-time notifications when events occur in DZDESK.

Overview

Webhooks allow you to receive HTTP callbacks when events happen in DZDESK. Instead of polling the API, DZDESK pushes events to your endpoint.

Setting Up Webhooks

Creating a Webhook

1. Navigate to Settings > API > Webhooks
2. Click Add Webhook
3. Configure:
   • Endpoint URL
   • Events to subscribe
   • Secret key
4. Save and test

Configuration Fields

Field	Description
URL	Your HTTPS endpoint
Events	Which events to send
Secret	For signature verification
Active	Enable/disable webhook

Available Events

Request Events

Event	Trigger
request.created	New request created
request.updated	Request modified
request.status_changed	Status change
request.assigned	Assignment change
request.commented	Comment added
request.deleted	Request deleted

SLA Events

Event	Trigger
sla.warning	SLA at risk
sla.breach	SLA breached

User Events

Event	Trigger
user.created	User provisioned
user.updated	User modified
user.deactivated	User deactivated

Webhook Payload

Standard Format

{
  "id": "whk_abc123",
  "event": "request.created",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "id": "req_123",
    "title": "Cannot access email",
    "status": "open",
    "priority": "high",
    "requester": {
      "id": "usr_123",
      "email": "john@company.com"
    },
    "assignedTo": null,
    "createdAt": "2024-01-15T14:30:00Z"
  }
}

Event-Specific Data

request.status_changed

{
  "event": "request.status_changed",
  "data": {
    "id": "req_123",
    "previousStatus": "open",
    "newStatus": "in_progress",
    "changedBy": {
      "id": "usr_456",
      "email": "jane@company.com"
    }
  }
}

sla.warning

{
  "event": "sla.warning",
  "data": {
    "requestId": "req_123",
    "slaType": "resolution",
    "targetTime": "2024-01-15T18:00:00Z",
    "percentElapsed": 75,
    "timeRemaining": "2h 30m"
  }
}

Security

Signature Verification

Each webhook includes a signature header:

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

Verifying Signature

const crypto = require('crypto');

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

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return f"sha256={expected}" == signature

Best Practices

1. Always verify signatures
2. Use HTTPS endpoints only
3. Respond quickly (< 5 seconds)
4. Process async if needed

Handling Webhooks

Response Requirements

Response	Action
2xx	Success, event delivered
4xx	Bad request, won't retry
5xx	Server error, will retry
Timeout	Will retry

Processing Pattern

app.post('/webhook', (req, res) => {
  // Verify signature first
  if (!verifyWebhook(req.body, req.headers['x-dzdesk-signature'], SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Acknowledge quickly
  res.status(200).send('OK');
  
  // Process async
  processWebhook(req.body);
});

Retry Policy

Failed webhooks are retried:

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

After 5 failures:

• Webhook marked as failing
• Admin notified
• Manual retry available

Testing Webhooks

Test Endpoint

Use the dashboard to send test events:

1. Go to webhook settings
2. Click Send Test
3. Select event type
4. Verify receipt

Local Development

For local testing:

• Use ngrok or similar
• Test with dashboard
• Check signature verification

Webhook Management

Viewing History

1. Go to Settings > API > Webhooks
2. Select webhook
3. View Delivery History

Delivery Details

See for each delivery:

• Timestamp
• Event type
• Response status
• Response time
• Response body

Disabling Webhooks

To pause a webhook:

1. Open webhook settings
2. Toggle Active off
3. Events queued (optional)

Use Cases

Integration with Ticketing

// Create ticket in another system
app.post('/webhook', async (req, res) => {
  res.status(200).send('OK');
  
  if (req.body.event === 'request.created') {
    await otherSystem.createTicket({
      externalId: req.body.data.id,
      title: req.body.data.title
    });
  }
});

Slack Notifications

// Send to Slack on SLA warning
if (event === 'sla.warning') {
  await slack.send({
    channel: '#support',
    text: `⚠️ SLA at risk: ${data.requestId}`
  });
}

Monitoring Dashboard

// Update real-time dashboard
if (event.startsWith('request.')) {
  websocket.broadcast({
    type: 'request_update',
    data: req.body.data
  });
}

Troubleshooting

Not Receiving Webhooks

• Verify endpoint URL correct
• Check webhook is active
• Confirm events selected
• Review delivery history

Signature Invalid

• Ensure using raw body
• Check secret matches
• Verify encoding

Timeouts

• Respond quickly
• Process asynchronously
• Check server performance

Related Topics

• Authentication - API authentication
• Events API - Polling for events
• Integrations - Integration guide