Webhooks

Receive real-time notifications when events occur in Mployr.

Overview

Webhooks allow you to receive HTTP POST requests to your server when specific events occur in the Mployr system. This enables real-time integrations without polling the API.

How Webhooks Work

Configure a webhook endpoint URL in your Mployr settings
Select which events you want to receive
Mployr sends a POST request to your URL when events occur
Your server processes the event and returns a 2xx response

Event Types

Subscribe to specific event types to receive relevant notifications:

People

Event	Description
person.created	A new person record was created
person.updated	A person record was updated
person.deleted	A person record was deleted

Documents

Event	Description
document.created	A new document was generated
document.signed	A document was signed
document.expired	A document signing request expired

Payroll

Event	Description
payrun.created	A new pay run was created
payrun.approved	A pay run was approved
payrun.completed	A pay run was completed

Leave

Event	Description
leave.requested	A leave request was submitted
leave.approved	A leave request was approved
leave.rejected	A leave request was rejected

Webhook Payload

All webhook payloads follow a consistent structure:

webhook-payload.json

{
  "id": "evt_abc123xyz",
  "type": "person.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": 42,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "date_of_birth": "1990-05-15",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Field	Description
id	Unique event identifier
type	Event type (e.g., person.created)
created_at	ISO 8601 timestamp of the event
data	Event-specific payload data

Signature Verification

All webhook requests include a signature header for verification. Always verify the signature before processing webhook events.

Security Requirement

Always verify webhook signatures to ensure requests are from Mployr and haven't been tampered with.

Signature Header

The signature is included in the X-Webhook-Signature header:

X-Webhook-Signature: sha256=abc123def456...

Verification Examples

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// Express.js webhook handler
app.post('/webhooks/mployr', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case 'person.created':
      handlePersonCreated(event.data);
      break;
    case 'person.updated':
      handlePersonUpdated(event.data);
      break;
    // Handle other event types...
  }

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

Configuring Webhooks

Create a webhook endpoint via the API or through the Mployr dashboard:

create-webhook.sh

curl -X POST https://api.mployr.com.au/v1/webhooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/mployr",
    "events": ["person.created", "person.updated", "document.signed"],
    "active": true
  }'

Best Practices

Respond Quickly

Return a 2xx response within 30 seconds. Process events asynchronously using a job queue if needed.

Handle Duplicates

Use the event ID to deduplicate. Webhooks may be delivered multiple times if your server doesn't respond in time.

Use HTTPS

Always use HTTPS endpoints in production to protect webhook payloads in transit.

Monitor Failures

Set up monitoring for webhook failures. After multiple failures, webhooks may be automatically disabled.

Retry Policy

If your endpoint doesn't respond with a 2xx status, Mployr will retry the webhook with exponential backoff:

1st retry: 1 minute after initial attempt
2nd retry: 5 minutes after 1st retry
3rd retry: 30 minutes after 2nd retry
4th retry: 2 hours after 3rd retry
5th retry: 24 hours after 4th retry

After 5 failed attempts, the webhook event is marked as failed and won't be retried.

Next Steps

Learn about historical data tracking with SCD Type 2.