Webhooks

Receive real-time notifications when events occur in PROIGN modules.

Overview

Webhooks allow your application to receive HTTP POST requests when events happen:

• Order status changes in Fulfillment
• Documents signed in Sign
• Tickets created in Support/Helpdesk
• Stock alerts in Inventory
• And more across all modules

Setting Up Webhooks

Create a subscription via the Events module API:

POST /api/[tenant]/subscriptions

{
  "event_type": "order.shipped",
  "target_module": "external",
  "webhook_url": "https://your-app.com/webhooks/proign",
  "secret": "your-webhook-secret",
  "filter": {
    "shipping_method": "express"
  }
}

Event Types

Fulfillment Events

Rewards Events

Sign Events

Support/Helpdesk Events

Inventory Events

Campaign Events

QR Code Events

Tax Events

Aftersale & Upgrade Events

Catalog Events

MES Events

Webhook Payload

Each webhook delivery includes:

{
  "id": "evt_abc123",
  "type": "order.shipped",
  "timestamp": "2024-01-15T10:30:00Z",
  "tenant_id": "tenant_xyz",
  "data": {
    "order_id": "ord_123",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "shipped_at": "2024-01-15T10:30:00Z"
  }
}

Signature Verification

All webhooks include an HMAC signature for verification. The signature is in theX-Proign-Signature header.

// Node.js verification example
const crypto = require('crypto');

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

  return signature === `sha256=${expected}`;
}

// Express middleware
app.post('/webhooks/proign', (req, res) => {
  const signature = req.headers['x-proign-signature'];

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

  // Process webhook
  const { type, data } = req.body;
  console.log(`Received ${type} event`, data);

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

Delivery & Retries

Webhook delivery includes automatic retries:

• Up to 5 retry attempts on failure
• Exponential backoff (1min, 5min, 30min, 2hr, 24hr)
• Timeout: 30 seconds per request
• Success: HTTP 2xx response

Retry Headers

Retry requests include additional headers:

Best Practices

• Respond quickly - Return 200 immediately, process async
• Handle duplicates - Use event ID for idempotency
• Verify signatures - Always validate before processing
• Use HTTPS - Only HTTPS endpoints are supported
• Monitor failures - Set up alerts for failed deliveries

Testing Webhooks

Test your webhook endpoint before going live:

# Send test event
POST /api/[tenant]/subscriptions/[id]/test

# View delivery history
GET /api/[tenant]/subscriptions/[id]/deliveries

Related