Integrations•7 min read

Webhooks

Get real-time notifications when events happen in SimpleStaff.

What Are Webhooks?

Webhooks let you receive automatic notifications when events happen in SimpleStaff. Instead of constantly polling the API, your server gets a POST request whenever something changes.

Use cases: Sync schedules to other systems, send custom notifications, trigger workflows in Zapier/Make, update your internal databases.

Creating a Webhook

Navigate to Webhooks

Go to Settings → Integrations → Webhooks.

Click "Add Webhook"

Enter a name for your webhook (e.g., "Sync to Slack").

Enter Your Endpoint URL

Provide the HTTPS URL where you want to receive events.

Select Events

Choose which events trigger this webhook.

Save and Test

Save the webhook, then click "Send Test" to verify it's working.

Available Events

Schedule Events

schedule.published— Schedule published

schedule.updated— Schedule modified

Shift Events

shift.created— New shift added

shift.updated— Shift modified

shift.deleted— Shift removed

shift.swapped— Shift swap completed

Time-Off Events

timeoff.requested— New request submitted

timeoff.approved— Request approved

timeoff.denied— Request denied

Employee Events

employee.created— New employee added

employee.updated— Employee info changed

employee.deactivated— Employee removed

Webhook Payload

Each webhook sends a JSON payload with event details:

{
  "id": "evt_abc123",
  "type": "shift.created",
  "timestamp": "2024-01-15T09:00:00Z",
  "data": {
    "id": "shift_xyz789",
    "date": "2024-01-20",
    "start_time": "09:00",
    "end_time": "17:00",
    "employee": {
      "id": "emp_123",
      "name": "John Smith",
      "email": "john@example.com"
    },
    "position": "Server",
    "location": "Downtown"
  }
}

Verifying Webhook Signatures

Each webhook includes a signature header to verify it came from SimpleStaff:

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

To verify, compute HMAC-SHA256 of the raw request body using your webhook secret:

const crypto = require('crypto');

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

Important: Always verify webhook signatures to prevent spoofing attacks.

Retry Policy

If your endpoint doesn't respond with 2xx within 30 seconds, we retry:

Attempt	Delay
2nd attempt	1 minute
3rd attempt	5 minutes
4th attempt	30 minutes
5th attempt	2 hours
6th attempt (final)	24 hours

After 6 failed attempts, the webhook is marked as failed. You'll receive an email notification.

Best Practices

Respond quickly

Return 200 immediately, then process the event asynchronously.

Handle duplicates

Use the event ID to detect and ignore duplicate deliveries.

Verify signatures

Always check the signature header before processing.

Use HTTPS

Webhook URLs must use HTTPS for security.

API Access Zapier Integration Calendar Sync Enterprise Plans

Need help with webhooks?

Contact Support