Implementation

Event processing requirements

Your webhook endpoint should implement the following processing pattern:

1. Accept POST requests containing JSON event data

2. Validate the event structure before processing

3. Return HTTP 200-299 immediately to acknowledge receipt

4. Process events asynchronously to prevent timeout

5. Implement idempotency using the transaction Id field

6. Handle duplicate events gracefully (at-least-once delivery may send duplicates)

Example webhook implementation

// Node.js/Express example
app.post('/relay-webhook', async (req, res) => {
  try {
    // Immediately acknowledge receipt
    res.status(200).json({ received: true });
    
    // Process asynchronously
    processEventAsync(req.body);
  } catch (error) {
    // Log error but still return 200
    console.error('Error acknowledging event:', error);
    res.status(200).json({ received: true, error: 'logged' });
  }
});

async function processEventAsync(event) {
  // Check for duplicate using transaction ID
  if (await isDuplicate(event.Id)) {
    console.log(`Duplicate event ${event.Id} - skipping`);
    return;
  }
  
  // Process the event
  await saveTransaction(event);
  await updateInventory(event.SoldItems);
  await updateReporting(event);
}

# Python/Flask example
@app.route('/relay-webhook', methods=['POST'])
def relay_webhook():
    # Get event data
    event = request.get_json()
    
    # Immediately acknowledge receipt
    response = {'received': True}
    
    # Queue for async processing
    queue_event_processing(event)
    
    return jsonify(response), 200

def process_event(event):
    # Check for duplicates
    if is_duplicate(event['Id']):
        logger.info(f"Duplicate event {event['Id']} - skipping")
        return
    
    # Process the event
    save_transaction(event)
    update_inventory(event['SoldItems'])
    update_reporting(event)

Idempotency implementation

Implement idempotency using the transaction Id field to prevent duplicate processing:

// Example idempotency check using Redis
async function isDuplicate(transactionId) {
  const key = `processed:${transactionId}`;
  const exists = await redis.exists(key);
  
  if (exists) {
    return true;
  }
  
  // Mark as processed with 24-hour expiry
  await redis.setex(key, 86400, 'processed');
  return false;
}

-- Example using database table
CREATE TABLE processed_transactions (
  transaction_id VARCHAR(36) PRIMARY KEY,
  processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_processed_at (processed_at)
);

-- Check for duplicate
SELECT COUNT(*) FROM processed_transactions 
WHERE transaction_id = ?;

-- Mark as processed
INSERT INTO processed_transactions (transaction_id) 
VALUES (?)
ON DUPLICATE KEY UPDATE processed_at = CURRENT_TIMESTAMP;

---