Webhooks

Webhooks allow your external systems to receive real-time notifications when events occur in your business. Connect your POS, inventory system, accounting software, or custom applications to TypeMenu and react instantly to orders, payments, and inventory changes.

Plan Requirement: Webhooks are available on Professional and Enterprise plans.

What Are Webhooks?

Webhooks are automated HTTP POST requests sent to a URL you specify whenever certain events occur. Your system receives instant notifications the moment something happens, enabling real-time integrations.

Common Use Cases

• Order management systems: Receive new orders instantly for processing
• Kitchen display systems: Get notified when orders are placed or updated
• Accounting software: Automatically record payments and refunds
• Inventory systems: React to low stock or out-of-stock alerts
• Customer notifications: Trigger custom workflows when customers register
• Analytics platforms: Track events in real-time

Accessing Webhook Settings

From the Dashboard

1. Go to Settings → Integrations
2. Click the Webhooks tab at the top of the page
3. View your webhook endpoints or create new ones

Creating a Webhook Endpoint

Step 1: Add New Webhook

1. Click “Add Webhook” button
2. Fill in the endpoint details:
   • Name: A friendly name to identify this endpoint (e.g., “Kitchen Display”, “Accounting System”)
   • Endpoint URL: The HTTPS URL where webhook payloads will be sent

Step 2: Select Events

Choose which events should trigger this webhook. Events are grouped by category:

Orders

Event	When Triggered
Order Created	A new order is placed
Order Updated	An order is modified
Order Confirmed	An order is confirmed/accepted
Order Preparing	An order begins preparation
Order Ready	An order is ready for collection/delivery
Order Completed	An order is marked as completed
Order Cancelled	An order is cancelled

Payments

Event	When Triggered
Payment Received	A payment is successfully received
Payment Failed	A payment attempt fails
Payment Refunded	A payment is refunded

Customers

Event	When Triggered
Customer Created	A new customer account is created
Customer Updated	Customer details are updated

Products

Event	When Triggered
Product Created	A new product is created
Product Updated	A product is modified
Product Deleted	A product is deleted

Inventory

Event	When Triggered
Inventory Low Stock	Inventory falls below the low stock threshold
Inventory Out of Stock	A product goes out of stock
Inventory Restocked	Out-of-stock inventory is replenished

Step 3: Configure Security (Recommended)

Enable Signature Verification

• Adds an HMAC signature header to verify webhook authenticity
• Strongly recommended for production use
• Helps prevent spoofed requests from malicious actors

When you create a webhook with signature verification enabled, you’ll receive a signing secret. This secret is shown only once - copy and store it securely.

Step 4: Custom Headers (Optional)

Add custom headers to include with webhook requests:

• Useful for authentication tokens
• Pass API keys to your endpoint
• Include custom identifiers

Click “Add Header” and enter:

• Header name: The HTTP header name
• Header value: The value to send

Step 5: Create the Webhook

Click “Create Webhook” to save your endpoint.

Managing Webhook Endpoints

Viewing Endpoints

Your webhooks list shows:

• Name: Endpoint identifier
• URL: Where webhooks are sent
• Status: Active or Disabled
• Subscribed events: Which events trigger this webhook
• Delivery count: Total deliveries attempted
• Last success/failure: Recent activity status
• Created date: When the endpoint was added

Editing an Endpoint

1. Click “View” on any endpoint
2. Click “Edit” to modify settings
3. Update name, URL, events, or headers
4. Save your changes

Enabling/Disabling Endpoints

• Click “Disable” to temporarily stop sending webhooks
• Click “Enable” to resume sending
• Useful for maintenance or troubleshooting

Deleting an Endpoint

1. Click “Delete” on the endpoint
2. Confirm the deletion
3. This action cannot be undone

Webhook Delivery

How Delivery Works

When an event occurs:

1. TypeMenu creates a webhook delivery
2. The payload is sent to your endpoint URL
3. Your server should respond with a 2xx status code
4. Failed deliveries are automatically retried

Retry Policy

Failed deliveries are retried with exponential backoff:

• Retries occur automatically
• Maximum retry attempts are configured per endpoint
• Failed attempts are logged for debugging

Delivery Statuses

Status	Meaning
Pending	Delivery queued, not yet attempted
Sending	Currently being delivered
Succeeded	Successfully delivered (2xx response)
Failed	Delivery failed, will be retried
Dead	All retry attempts exhausted

Viewing Delivery Logs

Recent Deliveries

On each endpoint’s detail page, view the last 20 delivery attempts showing:

• Event type: Which event triggered the delivery
• Status: Current delivery status
• Response code: HTTP status from your server
• Attempt count: Number of delivery attempts
• Timestamps: When created and last updated

Global Delivery Logs

Click “View Logs” to see all deliveries across all endpoints:

• Last 50 deliveries from all webhooks
• Filter and search capabilities
• Click any delivery to view full details

Delivery Details

Click any delivery to view:

• Delivery ID: Unique identifier
• Event: What triggered this delivery
• Endpoint: Which webhook received it
• Status: Current state
• Attempts: Number of tries
• Response code: Last HTTP response
• Error message: If delivery failed
• Payload: The full JSON data sent

Webhook Payload Format

Webhooks are sent as HTTP POST requests with JSON payloads:

POST /your-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Webhook-Signature: sha256=...
X-Webhook-Event: order.created
X-Webhook-Delivery-Id: 01HXYZ...

{
  "event": "order.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Headers

Header	Description
Content-Type	Always application/json
X-Webhook-Event	The event type (e.g., order.created)
X-Webhook-Delivery-Id	Unique delivery identifier
X-Webhook-Signature	HMAC signature (if enabled)

Signature Verification

Why Verify Signatures?

Signature verification ensures webhook requests genuinely come from TypeMenu and haven’t been tampered with.

How It Works

1. TypeMenu creates a signature using your signing secret
2. The signature is included in the X-Webhook-Signature header
3. Your server recreates the signature and compares
4. If they match, the request is authentic

Verifying in Your Application

// Pseudocode example
signature_header = request.headers['X-Webhook-Signature']
expected_signature = 'sha256=' + HMAC_SHA256(signing_secret, request.body)

if (signature_header == expected_signature) {
    // Request is authentic - process it
} else {
    // Request may be spoofed - reject it
}

Regenerating Signing Secrets

If your signing secret is compromised:

1. Edit the webhook endpoint
2. Check “Regenerate Signing Secret”
3. Save changes
4. Copy the new secret immediately
5. Update your application with the new secret

Important: The old secret is invalidated immediately. Update your application before saving to avoid failed deliveries.

Best Practices

Endpoint Security

• Use HTTPS: Always use secure URLs for webhook endpoints
• Verify signatures: Enable and check signature verification
• Validate payloads: Verify the data structure before processing
• Use authentication: Add API keys via custom headers

Handling Webhooks

• Respond quickly: Return 2xx within 30 seconds
• Process asynchronously: Queue webhook data for background processing
• Handle duplicates: Webhooks may be delivered more than once
• Log everything: Keep records for debugging

Reliability

• Monitor failures: Check delivery logs regularly
• Set up alerts: Monitor for repeated failures
• Test endpoints: Verify webhooks work before going live
• Plan for downtime: Have a strategy for missed webhooks

Troubleshooting

Webhooks Not Being Received

• Check endpoint status: Ensure the webhook is Active
• Verify URL: Confirm the URL is correct and accessible
• Check firewall: Ensure your server accepts requests from TypeMenu
• Review logs: Check delivery logs for error messages

Signature Verification Failing

• Check secret: Ensure you’re using the correct signing secret
• Verify algorithm: Use HMAC-SHA256
• Check encoding: Compare raw request body, not parsed JSON

High Failure Rate

• Check server availability: Ensure your endpoint is up
• Review response times: Respond within 30 seconds
• Check response codes: Return 2xx for success
• Review error messages: Check delivery logs for details

Deliveries Marked as Dead

• Check endpoint health: Verify your server is responding
• Review all attempts: Look at the full delivery history
• Consider re-creating: Delete and recreate the webhook if needed

Permissions

Access to webhooks requires appropriate permissions:

Permission	What It Allows
View Webhooks	See webhook endpoints and logs
Edit Webhooks	Create, edit, and delete endpoints

Contact your administrator if you need webhook access.

Related Guides

• Notification Settings - Email and SMS notifications
• Orders - Order management
• Inventory - Stock management

---

Webhooks provide powerful integration capabilities for automating your business processes. Start with essential events like order notifications, then expand as your integration needs grow.