Webhooks

Webhooks allow external systems to receive real-time notifications when events occur in ERPX.

How Webhooks Work

ERPX Event → Webhook Queue → HTTP POST → Your Endpoint → Acknowledge (200 OK)

When an event occurs, ERPX sends an HTTP POST request to your configured endpoint with event details in the request body.

Setting Up Webhooks

Available Events

Document Events

Sales Events

Inventory Events

HR Events

Webhook Payload

Event Structure

{
  "id": "evt_abc123",
  "event": "sales_order.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "so_001",
    "customer": "Acme Corporation",
    "total": 10599.8,
    "items": 2,
    "status": "draft"
  },
  "metadata": {
    "userId": "usr_123",
    "userName": "John Doe",
    "ipAddress": "192.168.1.100"
  }
}

Signature Verification

ERPX signs webhook payloads using HMAC-SHA256. Always verify the signature to ensure authenticity:

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${hash}`),
  );
}

The signature is sent in the X-ERPX-Signature header.

Retry Policy

If your endpoint doesn’t respond with a 2xx status code, ERPX retries with exponential backoff:

After 5 failed attempts, the webhook is deactivated and an admin notification is sent.

Webhook Logs

View webhook delivery logs in Settings → Webhooks → Logs:

• Delivery status (success/failure)
• Response status code
• Response body
• Delivery duration
• Retry history

Best Practices

1. Respond quickly — Return 200 OK immediately, process asynchronously
2. Handle duplicates — Use the event id for idempotency
3. Verify signatures — Always validate the X-ERPX-Signature header
4. Use HTTPS — Webhook URLs must use HTTPS
5. Monitor failures — Set up alerts for webhook delivery failures