API and Webhooks

Integrate your Mozhe store with external systems using webhooks and API integrations. This guide covers webhook events, integration patterns, and best practices for building custom integrations.

Overview

Mozhe provides integration capabilities through:

1. Webhooks - Receive notifications when events occur in your store
2. tRPC API - Internal API used by the dashboard (not currently exposed for external use)
3. Payment Webhooks - Callbacks from payment processors

Understanding Webhooks

Webhooks are HTTP callbacks that notify your external systems when specific events occur in your store. Instead of polling for changes, your system receives real-time notifications.

How Webhooks Work

1. Event occurs in your store (e.g., new order)
        ↓
2. Mozhe sends HTTP POST to your webhook URL
        ↓
3. Your system receives and processes the event
        ↓
4. Your system responds with 200 OK

Payment Webhooks

Payment processors send webhooks to confirm payment status. These are configured automatically based on your payment settings.

Chipcard Payment Webhooks

For stores using Chipcard payment processing, webhooks handle:

3D Secure Authentication Flow:

1. Customer initiates payment
2. Bank redirects customer for 3D Secure authentication
3. After authentication, bank redirects to Mozhe webhook
4. Webhook endpoint processes the payment authorization
5. Customer is redirected to success or error page

Webhook Endpoint:

POST /api/webhooks/chipcard

Payload Fields:

Response Codes:

AllSecure Payment Webhooks

For stores using AllSecure payment processing:

Webhook Endpoint:

GET /api/webhooks/allsecure

Query Parameters:

KOPA Payment Webhooks

For stores using KOPA payment processing:

Webhook Endpoint:

POST /api/webhooks/kopa

Events:

• Payment authorized
• Payment captured
• Payment failed

Resend Email Webhooks

Email delivery notifications from Resend:

Webhook Endpoint:

POST /api/webhooks/resend

Events:

• Email delivered
• Email bounced
• Email marked as spam

Integration Patterns

Order Synchronization

To sync orders with an external system (ERP, fulfillment, etc.):

Recommended Approach:

1. Use the dashboard to export orders
2. Implement a scheduled job to query recent orders
3. Track processed orders by timestamp or ID

Order Data Available:

• Order number and status
• Customer information
• Line items and quantities
• Shipping address
• Payment status

Inventory Updates

For keeping inventory synchronized:

Manual Approach:

• Export inventory from dashboard
• Import updates via product management

Bulk Operations:

• Use CSV import for large updates
• Available in Dashboard > Products > Import

Customer Data Export

For CRM integration or marketing tools:

Available Data:

• Customer name and email
• Order history
• Account creation date

Export Methods:

• Dashboard export functionality
• Manual data extraction

Shipping Webhooks

For stores using integrated shipping providers:

D-Express Webhooks

Webhook Endpoint:

POST /api/webhooks/dexpress

Events:

• Shipment created
• Package in transit
• Package delivered
• Delivery exception

Vercel Analytics Webhooks

For receiving web analytics data:

Webhook Endpoints:

POST /api/webhooks/vercel-analytics
POST /api/webhooks/vercel-speed-insights

Webhook Security

Verifying Webhook Requests

To ensure webhook requests are legitimate:

1. Check source IP - Verify requests come from expected IP ranges
2. Validate signatures - Some providers include HMAC signatures
3. Use HTTPS - Always use HTTPS endpoints
4. Implement idempotency - Handle duplicate webhook deliveries

Recommended Security Headers

When implementing webhook receivers:

Content-Type: application/json
X-Webhook-Signature: [signature if provided]

Handling Failures

If your webhook endpoint returns an error:

1. Payment processors typically retry several times
2. Implement logging to track failed webhooks
3. Build retry logic for critical integrations

Building Custom Integrations

API Authentication (Future)

Public API access is not currently available. For custom integration needs:

1. Contact Mozhe support
2. Describe your integration requirements
3. Discuss available options

Dashboard Export APIs

The dashboard provides export functionality for:

• Products (CSV)
• Orders (CSV/JSON)
• Customers (CSV)

Access exports via Dashboard > Settings > Export.

Custom Development

For advanced integrations requiring custom development:

1. Partner Program - Mozhe partners can access development tools
2. Enterprise Plans - Custom API access may be available
3. Consultation - Technical consultation for complex integrations

Integration Examples

Example: Order Notification to Slack

While direct webhook forwarding isn't available, you can:

1. Set up email notifications for new orders
2. Use a service like Zapier to parse emails
3. Forward relevant data to Slack

Example: Inventory Sync with Spreadsheets

1. Export products from Dashboard
2. Update quantities in your spreadsheet
3. Re-import updated CSV

Example: Customer Export for Email Marketing

1. Navigate to Dashboard > Customers
2. Export customer list
3. Import into your email marketing platform
4. Set up consent tracking separately

Troubleshooting

Webhook Not Received

1. Verify your endpoint is publicly accessible
2. Check endpoint returns 200 status code
3. Review server logs for errors
4. Confirm firewall allows incoming connections

Payment Webhook Failures

1. Check order status in dashboard
2. Review payment processor dashboard for errors
3. Verify merchant credentials are correct
4. Contact support with transaction IDs

Duplicate Webhook Deliveries

1. Implement idempotency checks using transaction IDs
2. Store processed webhook IDs
3. Skip already-processed events

Best Practices

1. Respond quickly - Return 200 OK within 30 seconds
2. Process asynchronously - Queue long-running tasks
3. Log everything - Keep detailed logs for debugging
4. Handle failures gracefully - Build retry mechanisms
5. - Use HTTPS and validate requests

Limitations

Current limitations of the integration system:

• No public REST API for external applications
• Webhook events limited to payment processors
• No custom webhook configuration for store events
• API keys not available for external access

Requesting New Integrations

If you need integration capabilities not currently available:

1. Contact Support - Describe your use case
2. Feature Request - Submit via the feedback system
3. Partner Inquiry - For development partnership opportunities

Next Steps

• Currency and Tax - Configure payment processors
• Order Processing - Understand order workflows
• Quick Start - Complete your store setup