Webhooks

# Webhooks Webhooks allow you to receive real-time notifications when events occur in your Microdil account. ## Overview Instead of polling the API for changes, webhooks push data to your application when events happen. ## Setting Up Webhooks 1. Go to your [application settings](/developer/apps/) 2. Navigate to the Webhooks tab 3. Click "Add Webhook" 4. Enter your webhook URL 5. Select events to subscribe to 6. Save and note your webhook secret ## Webhook Structure When an event occurs, we send a POST request to your webhook URL: ```json { "event": "order.created", "timestamp": "2026-03-10T15:30:00Z", "data": { "order_id": 12345, "customer_name": "John Doe", "total": 99.99, "status": "pending" }, "signature": "sha256=abc123..." } ``` ## Verifying Webhook Signatures Always verify that webhooks come from Microdil by checking the signature: ### Python Example ```python import hmac import hashlib def verify_webhook(payload, signature, secret): computed_signature = hmac.new( secret.encode(), payload.encode(), hashlib.sha256 ).hexdigest() expected_signature = f"sha256={computed_signature}" return hmac.compare_digest(signature, expected_signature) ``` ### Node.js Example ```javascript const crypto = require('crypto'); function verifyWebhook(payload, signature, secret) { const computed = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); const expected = `sha256=${computed}`; return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } ``` ## Webhook Requirements Your webhook endpoint must: 1. **Respond quickly** - Return 2xx status within 5 seconds 2. **Be publicly accessible** - Must accept POST requests from internet 3. **Handle retries** - We retry failed deliveries with exponential backoff 4. **Verify signatures** - Always validate webhook authenticity ## Available Events - `order.created` - New order created - `order.completed` - Order completed - `order.cancelled` - Order cancelled - `payment.received` - Payment received - `payment.failed` - Payment failed - `inventory.low` - Low inventory alert - `user.registered` - New user registered - `reservation.created` - New reservation ## Testing Webhooks Use tools like: - **ngrok** - Create public URLs for local development - **webhook.site** - Test webhook payloads - **RequestBin** - Inspect webhook requests ## Retry Policy If your endpoint fails to respond with 2xx: - **1st retry**: After 5 seconds - **2nd retry**: After 25 seconds - **3rd retry**: After 125 seconds - **4th retry**: After 625 seconds - **Final retry**: After 3125 seconds After 5 failed attempts, the webhook is marked as failed. ## Monitoring View webhook delivery logs in your [developer dashboard](/developer/).