Introduction

What is a Webhook?

A webhook is an automated communication method that sends real-time information to your application when specific events occur. Unlike traditional API calls where you poll for data regularly, webhooks push data to your endpoint as events happen.

Simple example:

1. A customer places an order
2. Geins immediately sends order details to your webhook URL
3. Your application processes the order (trigger fulfillment, send confirmation, etc.)

Why Use Webhooks?

Real-Time Efficiency

Receive data instantly when events occur. No need to repeatedly check for updates.

Reduced Server Load

Polling requires constant requests. Webhooks only send data when there's something new.

• Polling: 1,000 requests/hour, 2 orders
• Webhooks: 2 requests/hour, 2 orders

Instant Responsiveness

React immediately to changes:

• Trigger fulfillment when orders are placed
• Update search indexes when products change
• Send emails when customers register
• Sync inventory across systems in real-time

Quick Start

1. Create Your Webhook Endpoint

Set up an endpoint that receives webhook POST requests:

// Example: Node.js + Express
app.post('/webhooks/geins', (req, res) => {
  const { entity, action, id } = req.body;
  
  console.log(`${entity} ${action}: ${id}`);
  
  // Process the event
  // ... your logic here ...
  
  res.status(200).send('OK');
});

2. Register the Webhook

Create a webhook in Geins Management API:

curl -X POST "https://mgmtapi.geins.io/API/Webhook" \
     -H "Content-Type: application/json" \
     -H "X-ApiKey: {MGMT_API_KEY}" \
     -u "username:password" \
     -d '{
           "Entity": "Order",
           "Name": "Order Notifications",
           "Actions": "create,complete",
           "Method": "POST",
           "Url": "https://your-app.com/webhooks/geins",
           "Body": "{\"entity\":\"{{entity}}\",\"action\":\"{{action}}\",\"id\":\"{{id}}\"}",
           "Retry": true
         }'

3. Receive Events

When an order is created or completed, your endpoint receives:

{
  "entity": "Order",
  "action": "create",
  "id": "12345"
}

That's it! Your application now receives real-time order notifications.

Common Use Cases

E-commerce Operations

Order Management

• Trigger warehouse fulfillment when orders are placed
• Send customer notifications for order status changes
• Update accounting systems when orders are completed
• Track returns and refunds in external dashboards

Inventory Sync

• Update stock levels across multiple sales channels
• Trigger restock notifications when inventory changes
• Sync product data to external marketplaces
• Monitor price changes for competitive analysis

Customer Engagement

• Welcome new customers with onboarding emails
• Send "back in stock" notifications (ProductMonitor)
• Update CRM systems with customer changes

Integration Scenarios

ERP/Accounting Systems

• Sync orders to accounting software
• Update purchase prices and margins
• Track payment captures and refunds

Marketing Automation

• Add new customers to email campaigns
• Trigger personalized product recommendations
• Track customer lifecycle events

Analytics & Monitoring

• Send events to analytics platforms like Google Analytics or Mixpanel
• Monitor business metrics in real-time dashboards
• Track conversion funnels and user behavior

Communication Platforms

• Post notifications to Slack or Microsoft Teams
• Send SMS alerts for high-value orders
• Update support tickets when order status changes

What Can You Listen To?

Geins supports webhooks for the following entities:

Each entity supports different actions (create, update, delete, etc.). See the Entities and Actions Reference for complete details.

Example: Listen to Product Price Changes

Use the {{subEntity}} placeholder to track specific product changes:

{
  "Entity": "Product",
  "Actions": "update",
  "Body": "{\"productId\":\"{{id}}\",\"changeType\":\"{{subEntity}}\"}"
}

When a price changes, you receive:

{
  "productId": "12345",
  "changeType": "price"
}

Filter in your handler to process only price changes. See Placeholders Reference for details.

Key Features

Dynamic Placeholders

Customize webhook URLs and payloads with dynamic values:

{
  "Url": "https://api.example.com/{{entity}}/{{action}}",
  "Body": "{\"id\":\"{{id}}\",\"env\":\"{{environment}}\"}"
}

Learn more: Placeholders Reference

Retries on Failure

When Retry is set to true:

• Failed webhook deliveries are retried up to 3 times
• Retry interval: 10 minutes between attempts
• Same x-Idempotency-Key header used for all retry attempts

Idempotency

All webhook requests include special headers:

Granular Change Tracking

The {{subEntity}} placeholder tells you exactly what changed (e.g., price, stockBalance, image) without fetching the full entity.

Documentation Structure

This webhook documentation is organized for quick reference:

1. Entities and Actions - What events can you listen to?
2. Placeholders - How to customize webhook content
3. API Reference - Create, update, delete, and manage webhooks
4. Examples - Ready-to-use examples:
   • Mailchimp Integration
   • Slack Notifications
   • Microsoft Teams Alerts