Webhook Implementation

Now that you understand the processing flow and webhook events for each entity (Import, File, Document), here’s how to configure webhook delivery and implement robust webhook handlers.

Webhook Configuration

To receive state change events, you’ll need:

• Publicly accessible URL - Your endpoint must be reachable by Invofox systems
• IP allowlist configuration - Reference our public IP ranges for firewall configuration
• Optional HMAC signature - Configure a secret key that will be used to sign webhook notifications with HMAC for enhanced security and authenticity verification

Contact your account administrator for webhook setup, IP range information, and HMAC signature configuration.

Webhooks are triggered on state transitions and document updates, ensuring you receive timely updates without redundant notifications.

Webhook Event Structure

All webhook events follow this consistent structure:

• type - Event type identifier (matches state transitions)
• id - Unique event identifier (use for idempotent processing)
• timestamp - Event creation timestamp in ISO 8601 format
• data - Event payload containing the entity instance (Import, File, or Document object)
• version - Event schema version

Example Event

1
{
2
  "type": "document.processed",
3
  "id": "675e1a2b8f7d06899790871d",
4
  "timestamp": "2024-12-15T14:30:00.000Z",
5
  "data": { /* DOCUMENT DATA */ },
6
  "version": "1.0"
7
}

Note: Document data structure is being refined. Refer to the API reference for the complete and current document structure.

Webhook Implementation Best Practices

This section covers best practices for implementing robust webhook handlers that process Invofox webhook events reliably and efficiently.

Quick Acknowledgment Pattern

⚠️ Best Practice: Your webhook endpoint should respond with a 2xx status code in less than 30 seconds to ensure reliable delivery.

Why Quick Responses Matter:

• Prevents timeout failures and retries
• Maintains reliable event delivery
• Allows you to handle processing asynchronously

Recommended Pattern: Verify signature → Queue event → Respond immediately

1
import express from 'express';
2
import crypto from 'crypto';
3
4
const app = express();
5
app.use(express.json());
6
7
// Message queue (example: AWS SQS, RabbitMQ, Bull, etc.)
8
import { messageQueue } from './queue';
9
10
app.post('/webhook', async (req, res) => {
11
  // Step 1: Verify signature
12
  if (!verifyWebhookSignature(req.body, req.headers['x-invofox-signature'], process.env.WEBHOOK_SECRET)) {
13
    return res.status(401).json({ error: 'Invalid signature' });
14
  }
15
16
  // Step 2: Queue event for async processing
17
  await messageQueue.send({
18
    type: 'invofox-webhook',
19
    payload: req.body,
20
    receivedAt: Date.now()
21
  });
22
23
  // Step 3: Respond immediately
24
  res.status(200).json({ received: true });
25
});
26
27
function verifyWebhookSignature(requestBody: any, signature: string | undefined, secret: string): boolean {
28
  if (!signature || !secret) return false;
29
30
  const splitIndex = signature.indexOf('=');
31
  const algorithm = signature.slice(0, splitIndex);
32
  const receivedHmac = signature.slice(splitIndex + 1);
33
34
  const computedHmac = crypto
35
    .createHmac(algorithm, secret)
36
    .update(JSON.stringify(requestBody))
37
    .digest('base64');
38
39
  return computedHmac === receivedHmac;
40
}

Event ID and Idempotency

Every webhook event includes a unique id field. Use this to implement idempotent processing and prevent duplicate handling.

Why Idempotency Matters:

• Network issues may cause Invofox to retry delivery
• Your processing logic might trigger multiple times
• Event IDs ensure each event is processed exactly once

Error Handling and Retry Behavior

HTTP Status Codes:

Your webhook endpoint should return:

• 200-299: Success - Invofox will not retry
• 4xx: Client error - Invofox will not retry (your endpoint rejected the event)
• 5xx: Server error - Invofox will retry up to 3 times
• Timeout: Request times out after 30 seconds - Invofox will retry up to 3 times

Invofox Retry Strategy:

When your endpoint returns an error or times out, Invofox will automatically retry up to 3 times:

• Retry delays are based on your endpoint’s Retry-After response header (default: 300ms if not specified)
• Total attempts: Original request + 3 retries = 4 delivery attempts

After exhausting retries, failed webhook deliveries are logged and can be viewed in your webhook dashboard.

Security Best Practices

HMAC Signature Verification:

Always verify the HMAC signature when you configure a webhook secret. This ensures events are from Invofox.

Key Security Points:

1. Secret storage: Store webhook secrets in environment variables or secret management systems
2. HTTPS only: Webhook endpoints must use HTTPS in production
3. Validate signatures: Always verify HMAC signatures when secrets are configured (see API Reference for implementation)
4. IP allowlisting: Optional - configure your firewall to only accept requests from Invofox’s IP ranges (contact support)

Summary Checklist

• ✅ Quick acknowledgment: Respond with 200 in less than 30 seconds
• ✅ Async processing: Queue events and process asynchronously
• ✅ HMAC verification: Always verify signatures when secret is configured
• ✅ Idempotency: Use event id to prevent duplicate processing
• ✅ Error handling: Return appropriate HTTP status codes based on error type
• ✅ Security: Use HTTPS, secure secret storage, optional IP allowlisting