Webhooks

Learn how to set up and use webhooks for real-time notifications.

Real-time Event Notifications

Webhooks allow your application to receive instant notifications when events occur.

Supported Events

employee.created

When a new employee is created.

employee.updated

When employee information is updated.

employee.deleted

When an employee is deleted.

employee.status_changed

When employee status changes.

Webhook Payload Format

{
  "event": "employee.created",
  "data": {
    "id": "emp_1234567890",
    "email": "john@company.com",
    "firstName": "John",
    "lastName": "Doe",
    "department": "Engineering",
    "jobTitle": "Developer",
    "status": "active",
    "createdAt": "2024-03-13T14:22:00Z"
  },
  "timestamp": "2024-03-13T14:22:00Z",
  "signature": "sha256=abcd1234..."
}

Setting Up Webhooks

// Node.js/Express example
app.post('/webhooks/unduit', express.json(), (req, res) => {
  const { event, data } = req.body;

  // Verify signature
  if (!verifySignature(req)) {
    return res.status(401).send('Unauthorized');
  }

  // Handle the event
  switch (event) {
    case 'employee.created':
      handleEmployeeCreated(data);
      break;
    case 'employee.updated':
      handleEmployeeUpdated(data);
      break;
  }

  // Acknowledge receipt
  res.json({ success: true });
});

Security

Verify Signatures

Always verify webhook signatures using the webhook secret.

Use HTTPS Only

Webhook URLs must use HTTPS.

Handle Duplicates

Implement idempotent processing for retried webhooks.

Retry Policy

Attempt 1: Immediately
Attempt 2: 5 seconds later
Attempt 3: 30 seconds later
Attempt 4: 2 minutes later
Attempt 5: 15 minutes later (final)