Custom Webhook Integration for Frozen Food Delivery

Who This Guide Is For

Custom webhook integration suits businesses running:

• Proprietary e-commerce platforms built in-house or by agencies
• ERP systems with order management modules (SAP, Sage, Odoo, custom)
• Point-of-sale systems that manage delivery orders
• Order aggregators consolidating from multiple channels
• Workflow automation tools like Zapier, Make (Integromat), or n8n
• Mobile applications with direct ordering capability
• Any system that can make HTTP requests

If your platform has an “automation,” “integration,” or “webhook” feature—or if you have a developer who can add one—this integration will work.

How Webhook Integration Works

The concept is straightforward:

Your System                          Our System
    │                                     │
    │  ── HTTP POST (JSON payload) ──────>│
    │                                     │ Validate
    │                                     │ Create task
    │<──── Response (tracking number) ────│
    │                                     │
    │                                     │ Process delivery
    │                                     │ Send customer notifications
    │                                     │ Complete delivery

You send: Order and delivery details as JSON We return: Tracking number and order status We handle: Validation, routing, driver dispatch, customer notifications, proof of delivery

Integration Setup Process

Step 1: Contact Us

Email info@thefrozenfoodcourier.co.za or call +27 82 575 0085 with:

• Your platform/system name
• Sample payload (what your system can send)
• Expected order volume
• Delivery areas required (Gauteng, Western Cape, or both)

Step 2: Payload Negotiation

We’ll review your system’s native data format and configure our endpoint to accept it. This means you don’t need to rebuild your order data structure—we map your fields to our requirements.

Typical fields we need:

Field	Purpose	Required
Customer name	Delivery identification	Yes
Phone number	Driver contact & SMS notifications	Yes
Delivery address	Routing & scheduling	Yes
Order reference	Your internal tracking	Yes
Order contents	Load planning & documentation	Yes
Special instructions	Gate codes, contact preferences, notes	No

Your field names don’t need to match ours. If your system sends recipient_name instead of customer_name, or delivery_notes instead of special_instructions, we configure the mapping on our end.

Step 3: Endpoint Provisioning

Once we’ve agreed on the payload structure, we provision:

• Unique endpoint URL — Your dedicated webhook receiver
• Shared secret — For request signature verification

These credentials are specific to your integration. Keep the shared secret secure—it authenticates that requests genuinely originate from your system.

Step 4: Implementation

Configure your system to send HTTP POST requests to your endpoint URL when delivery orders are created.

Request requirements:

Component	Specification
Method	POST
Content-Type	application/json
Authentication	HMAC signature using shared secret
Payload	JSON object with agreed fields

Step 5: Testing

Send test orders through the integration. We’ll verify:

• Payload arrives correctly
• Field mapping works as expected
• Response returns properly
• Customer notifications trigger appropriately

Once testing passes, you’re live.

Technical Specification

Request Format

POST /webhook/inbound/{your-endpoint-id} HTTP/1.1
Host: [provided during setup]
Content-Type: application/json
X-Signature: [HMAC-SHA256 signature]
X-Timestamp: [Unix timestamp]

{
  ... your JSON payload ...
}

Authentication

We use HMAC-SHA256 signature verification to ensure requests originate from your system.

Signature calculation:

signature = HMAC-SHA256(
  key: your_shared_secret,
  message: timestamp + "." + request_body
)

Include in headers:

• X-Signature: The hex-encoded signature
• X-Timestamp: Unix timestamp used in signature (prevents replay attacks)

Example (pseudocode):

import hmac
import hashlib
import time
import json

shared_secret = "your_shared_secret_here"
payload = {"customer_name": "Jane Smith", ...}
body = json.dumps(payload)
timestamp = str(int(time.time()))

message = timestamp + "." + body
signature = hmac.new(
    shared_secret.encode(),
    message.encode(),
    hashlib.sha256
).hexdigest()

# Send with headers:
# X-Signature: {signature}
# X-Timestamp: {timestamp}

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "accepted",
  "tracking_number": "FFC-20260130-001234",
  "order_reference": "your-order-id",
  "message": "Delivery task created successfully"
}

Response fields:

Field	Description
status	accepted — task created successfully
tracking_number	Our reference for this delivery
order_reference	Your original order ID (echoed back)
message	Human-readable confirmation

Store the tracking_number in your system for reconciliation and customer service queries.

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "status": "error",
  "error_code": "INVALID_ADDRESS",
  "message": "Delivery address could not be validated. Please check suburb and postal code.",
  "order_reference": "your-order-id"
}

Common error codes:

Code	Meaning	Resolution
INVALID_SIGNATURE	HMAC verification failed	Check shared secret and signature calculation
MISSING_FIELD	Required field not provided	Add missing field to payload
INVALID_ADDRESS	Address validation failed	Verify address format and delivery zone coverage
INVALID_PHONE	Phone number format incorrect	Use international format (+27…)
OUTSIDE_DELIVERY_ZONE	Address not in serviceable area	Check delivery zones
DUPLICATE_ORDER	Order reference already exists	Check for duplicate submission

Example Payloads

These examples show typical structures. Your actual payload will be negotiated based on your system’s capabilities.

Minimal Payload

{
  "customer_name": "Jane Smith",
  "phone": "+27821234567",
  "address": "123 Main Road, Sandton, 2196",
  "order_reference": "ORD-12345",
  "contents": "2x 1kg Beef Mince, 1x Chicken Stir Fry Ready Meal"
}

Detailed Payload

{
  "customer_name": "Jane Smith",
  "phone": "+27821234567",
  "email": "jane@example.com",
  "address": {
    "street": "123 Main Road",
    "suburb": "Sandton",
    "city": "Johannesburg",
    "postal_code": "2196",
    "province": "Gauteng"
  },
  "order_reference": "ORD-12345",
  "contents": [
    {"sku": "BM001", "name": "Beef Mince 1kg", "quantity": 2},
    {"sku": "RM015", "name": "Chicken Stir Fry Ready Meal", "quantity": 1}
  ],
  "special_instructions": "Security estate - call on arrival. Code #4521 for pedestrian gate.",
  "preferred_delivery_date": "2026-02-01",
  "order_total": 245.00,
  "currency": "ZAR"
}

E-commerce Platform Native Format

If your platform exports orders in a specific structure, we can often accept it directly:

{
  "id": 98765,
  "created_at": "2026-01-30T14:23:00Z",
  "status": "paid",
  "shipping_address": {
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "082 123 4567",
    "address1": "123 Main Road",
    "address2": "Unit 5",
    "city": "Sandton",
    "zip": "2196"
  },
  "line_items": [
    {"title": "Beef Mince 1kg", "quantity": 2, "price": "89.00"},
    {"title": "Chicken Stir Fry Ready Meal", "quantity": 1, "price": "67.00"}
  ],
  "note": "Please call before delivery"
}

We’ll configure field mapping to extract what we need from your native format.

Workflow Automation Platforms

Using Zapier, Make (Integromat), n8n, or similar? These platforms can bridge between your order source and our webhook.

Typical setup:

1. Trigger: New order in your system (Airtable, Google Sheets, CRM, etc.)
2. Action: HTTP POST to our webhook endpoint
3. Configuration: Map fields from trigger to our required format
4. Authentication: Include HMAC signature via custom headers

Zapier example flow:

Trigger: New Row in Google Sheets
  ↓
Code Step: Calculate HMAC signature
  ↓
Action: Webhooks by Zapier → POST to our endpoint
  ↓
Action: Update Google Sheets with tracking number

Contact us for platform-specific guidance if you’re using workflow automation tools.

After Integration: What Happens Next

Once your webhook delivers order data to us:

Order Processing

1. Validation — We verify address, phone, and required fields
2. Acceptance — Task created, tracking number assigned
3. Scheduling — Order assigned to route based on delivery zone and capacity
4. Dispatch — Driver collects from your location or designated depot
5. Delivery — Temperature-controlled transport to customer
6. Completion — Proof of delivery captured, confirmation sent

Customer Notifications

Your customers receive automated updates via SMS and/or email:

• Order received confirmation
• Scheduled delivery date
• Driver dispatched notification
• Delivery completion with proof

→ Full notification workflow details

Status Updates to Your System

Need delivery status pushed back to your system? We can configure outbound webhooks to notify you of status changes:

• Task accepted
• Out for delivery
• Delivered successfully
• Delivery failed (with reason)

Discuss bidirectional integration requirements during setup.

Frequently Asked Questions

What if my system can't calculate HMAC signatures?

Some platforms (particularly no-code tools) have limited cryptographic capability. Contact us—we can discuss alternative authentication methods for your specific situation.

Can I send orders in batches?

Yes. You can POST multiple orders in a single request as a JSON array, or send individual requests per order. Discuss your preferred approach during payload negotiation.

What's the request timeout?

We respond within 5 seconds for valid requests. Configure your HTTP client with a 10-second timeout to allow for network variability.

How do I handle failed webhooks?

Implement retry logic with exponential backoff:

• First retry: 1 minute
• Second retry: 5 minutes
• Third retry: 15 minutes
• Alert your team if still failing

Store failed payloads for manual review and resubmission.

Can I test without creating real deliveries?

Yes. We provide a sandbox endpoint during setup that validates payloads and returns realistic responses without creating actual delivery tasks.

What about rate limiting?

Standard integration allows up to 60 requests per minute. If you’re processing high-volume flash sales or batch imports, let us know—we’ll adjust limits accordingly.

Getting Started

Ready to integrate?

1. Email us at info@thefrozenfoodcourier.co.za with:
   • Your platform/system description
   • Sample JSON payload your system can generate
   • Expected daily/weekly order volume
   • Required delivery areas
2. We’ll respond within 1 business day with:
   • Field mapping proposal
   • Integration timeline
   • Any questions about your setup
3. Setup typically takes 2-5 business days from initial contact to live integration, depending on your system’s complexity.

Related Resources

• E-Commerce Integration Guide — Overview of all integration options
• Shopify Integration — If you’re using Shopify
• WooCommerce Integration — If you’re using WooCommerce
• Wix Integration — If you’re using Wix
• Work Order Processing & Notifications — What happens after we receive your order
• Setting Up Frozen Food Shipping — E-commerce platform configuration
• Delivery Zones — Areas we service

Questions?

Contact us at info@thefrozenfoodcourier.co.za or call +27 82 575 0085.