Delivery & Reliability

How Netchex delivers webhook events, retry behavior, and how to handle duplicates

At-Least-Once Delivery

Netchex webhooks use at-least-once delivery. An event may be sent more than once — typically rare, but expected during retries. Always deduplicate using the id field.

async function processEvent(event) {
  const alreadyProcessed = await db.exists('processed_event_ids', event.id);
  if (alreadyProcessed) return;

  await db.insert('processed_event_ids', { id: event.id, processedAt: new Date() });
  // ... handle the event
}

Acknowledging Events

Respond with 200 OK as quickly as possible — before any heavy processing. Do not wait for database writes, downstream API calls, or other slow operations.

Netchex treats any non-2xx response as a failure and will retry.

app.post('/webhooks/netchex', express.json(), (req, res) => {
  if (req.query.token !== process.env.NETCHEX_WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  // Acknowledge immediately
  res.status(200).send('OK');

  // Process asynchronously
  queue.enqueue(req.body[0]);
});

Retry Behavior

When delivery fails, Netchex retries using an exponential backoff schedule for up to 24 hours. If all retries are exhausted, the event is dropped.

Events that are dropped after retry exhaustion are not recoverable from the webhook stream. Use the API to poll for any gaps in critical business processes (e.g., payroll confirmation).

Ordering

Event delivery order is not guaranteed. Two events for the same entity may arrive out of order.

Design your handler to be idempotent — applying the same event twice should produce the same result as applying it once.

When order matters, fetch current state from the API directly:

// Don't rely solely on what arrived in the event data
const employee = await netchexApi.get(`/api/v3/employees/${event.data.employeeId}`);

Implementation Checklist

Expose a publicly accessible HTTPS endpoint
Handle the Microsoft.EventGrid.SubscriptionValidationEvent and echo back the validationCode
Validate the token query parameter on every incoming request
Respond with HTTP 200 immediately upon receipt
Use the event id field to deduplicate any repeated deliveries
Use eventTime to handle out-of-order delivery if event sequencing matters
Fetch full resource details from the Netchex External API using the subject path or identifiers in data — do not rely solely on the event payload for authoritative data