Webhooks Guide

Receive real-time notifications when events occur in your Organiko.ai account

What are Webhooks?

Webhooks allow you to receive real-time HTTP notifications when specific events occur in your Organiko.ai account. Instead of polling the API for changes, Organiko.ai will POST event data to your specified endpoint.

🔔

Why Use Webhooks?

• Real-time notifications without polling
• Reduced API usage and costs
• Build event-driven workflows
• Sync data immediately as changes occur

Setting Up Webhooks

Create a Webhook Endpoint

Create an HTTPS endpoint on your server that can receive POST requests from Organiko.ai.

// Example: Express.js endpoint app.post('/webhooks/organiko', express.raw({ type: 'application/json' }), (req, res) => { const event = JSON.parse(req.body.toString('utf8')); // Process the event console.log('Received event:', event.type); // Acknowledge receipt res.status(200).json({ received: true }); });

Register the Webhook

Use the API to register your webhook endpoint and specify which events you want to receive.

POST /v1/webhooks { "url": "https://your-server.com/webhooks/organiko", "events": [ "order.certified", "order.allocated", "inventory.updated", "subscription.upgraded" ], "secret": "your-webhook-secret-key", "description": "Production webhook endpoint" }

Test Your Endpoint

Trigger test events from the Organiko.ai dashboard or API to verify your endpoint is working correctly.

Available Events

order.certified

Triggered when a purchase order is certified for organic compliance.

order.allocated

Triggered when inventory is allocated to a sales order.

inventory.updated

Triggered when inventory levels or details are updated.

inventory.low_stock

Triggered when inventory falls below minimum threshold.

subscription.upgraded

Triggered when a subscription tier is upgraded.

subscription.downgraded

Triggered when a subscription tier is downgraded.

subscription.cancelled

Triggered when a subscription is cancelled.

payment.failed

Triggered when a payment attempt fails.

payment.succeeded

Triggered when a payment is successfully processed.

compliance.alert

Triggered when a compliance issue is detected.

integration.connected

Triggered when a new integration is successfully connected.

integration.disconnected

Triggered when an integration is disconnected.

Event Payload Structure

All webhook events follow a consistent structure:

{ "id": "evt_abc123xyz", "type": "order.certified", "created": "2025-10-30T12:00:00Z", "data": { "object": "order", "id": "ord_xyz789", "order_number": "PO-2025-001", "status": "certified", "certification_date": "2025-10-30T12:00:00Z", "supplier": { "name": "Organic Farm Co.", "certification": "USDA-ORG-12345" }, "line_items": [ { "product_name": "Organic Tomatoes", "quantity": 500, "unit": "lbs", "certified": true } ] }, "previous_attributes": { "status": "pending" } }

idUnique identifier for the event

typeEvent type (e.g., "order.certified")

createdISO 8601 timestamp when event occurred

dataEvent-specific data (varies by event type)

previous_attributesPrevious values for updated fields (optional)

Signature Verification

Always verify webhook signatures to ensure requests are from Organiko.ai and haven't been tampered with.

⚠️

Security Warning

Never process webhooks without verifying signatures. This prevents attackers from spoofing events.

Node.js Example

import crypto from 'crypto'; function verifyWebhookSignature( payload: string, signature: string, secret: string ): boolean { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); // Use timing-safe comparison return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); } // In your webhook handler app.post('/webhooks/organiko', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-organiko-signature'] as string; const payload = req.body.toString('utf8'); const secret = process.env.WEBHOOK_SECRET; if (!verifyWebhookSignature(payload, signature, secret)) { console.error('Invalid webhook signature'); return res.status(401).send('Unauthorized'); } // Signature verified, process the event const event = JSON.parse(payload); // ... handle event });

Python Example

import hmac import hashlib def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool: """Verify webhook signature using HMAC-SHA256""" expected_signature = hmac.new( secret.encode('utf-8'), payload, hashlib.sha256 ).hexdigest() # Use timing-safe comparison return hmac.compare_digest(signature, expected_signature) # In your webhook handler (Flask example) @app.route('/webhooks/organiko', methods=['POST']) def handle_webhook(): signature = request.headers.get('X-Organiko-Signature') payload = request.get_data() secret = os.environ['WEBHOOK_SECRET'] if not verify_webhook_signature(payload, signature, secret): return jsonify({'error': 'Invalid signature'}), 401 # Signature verified, process the event event = request.get_json() # ... handle event

Best Practices

✓

Respond Quickly

Return a 200 OK response as quickly as possible. Process events asynchronously using a queue.

✓

Handle Idempotency

Use the event id to prevent processing the same event multiple times. Store processed event IDs.

✓

Use HTTPS

Webhook endpoints must use HTTPS in production. HTTP endpoints will be rejected.

✓

Implement Retry Logic

Organiko.ai will retry failed webhooks with exponential backoff. Your endpoint should handle duplicate deliveries gracefully.

✓

Monitor Webhook Health

Use the API to check webhook delivery status and failed deliveries. Set up alerts for persistent failures.

✓

Handle Unknown Events

Your code should gracefully handle unknown event types as new events may be added in the future.

Retry Behavior

If your endpoint doesn't respond with a 2xx status code, Organiko.ai will retry the webhook:

Attempt	Delay	Total Time
1 (initial)	Immediate	0 seconds
2	5 seconds	5 seconds
3	30 seconds	35 seconds
4	5 minutes	5m 35s
5	30 minutes	35m 35s
6 (final)	2 hours	2h 35m 35s

After 6 failed attempts, the webhook will be marked as failed and you'll receive a notification.

Testing Webhooks

1. Local Development with ngrok

Use ngrok to expose your local server to the internet for testing:

# Start your local server npm start # or python app.py, etc. # In another terminal, start ngrok ngrok http 3000 # Use the ngrok URL in your webhook configuration # Example: https://abc123.ngrok.io/webhooks/organiko

2. Send Test Events

Trigger test events via the API:

POST /v1/webhooks/:webhook_id/test { "event_type": "order.certified" }

3. Check Delivery Logs

View webhook delivery history and debug failed deliveries:

GET /v1/webhooks/:webhook_id/deliveries { "deliveries": [ { "id": "del_abc123", "event_id": "evt_xyz789", "status": "succeeded", "response_code": 200, "attempted_at": "2025-10-30T12:00:00Z" } ] }