Webhooks

Supplier API sends outbound signed webhooks for fulfillment lifecycle events.

Configuration Endpoints

Method	Path	Purpose
GET	/api/v1/webhooks	Current webhook URL, secret state, supported events
PUT	/api/v1/webhooks	Save/update webhook URL
POST	/api/v1/webhooks/test	Send test payload to URL
POST	/api/v1/webhooks/rotate-secret	Rotate signing secret (returned once)
GET	/api/v1/webhooks/deliveries	Delivery history and retry outcomes

Event Types

Supported event list is capability-aware (supports_dropship, supports_wholesale).

Order events:

• order.accepted (dropship, wholesale)
• order.shipped (dropship, wholesale)
• order.cancelled (dropship, wholesale)
• order.delivered (wholesale)

Trade-document events:

• document.poa.issued (wholesale)
• document.asn.issued (dropship, wholesale)
• document.invoice.issued (wholesale)
• document.credit_note.issued (dropship, wholesale)

GET /api/v1/webhooks returns only the events whose fulfillment_models match the supplier's capabilities, so a dropship-only supplier sees the dropship subset and a wholesale-capable supplier sees the wholesale events as well.

Payload Shape

Delivery payload envelope:

{
  "event": "order.shipped",
  "timestamp": "2026-04-24T06:55:20.000000+00:00",
  "supplier_id": "sup_...",
  "data": {
    "fulfillment_model": "dropship",
    "order_id": "dso_...",
    "purchase_order_id": null,
    "status": "shipped",
    "tracking_number": "TRACK123",
    "carrier": "Australia Post"
  }
}

Delivery Headers

Header	Description
Content-Type	application/json
X-Webhook-Event	Event type
X-Webhook-Delivery-Id	Unique delivery ID
X-Webhook-Timestamp	Event timestamp from payload
X-Webhook-Signature	sha256=<hex-hmac>
User-Agent	OKNowShop-Webhook/1.0

Signature Verification

Python example:

import hashlib
import hmac


def verify_signature(raw_body: bytes, secret: str, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Retry Policy

Supplier API retry schedule:

• 1 minute
• 5 minutes
• 15 minutes
• 1 hour
• 4 hours

After max attempts, delivery is marked exhausted.

URL Validation and Security

Webhook destinations are validated to reduce SSRF risk:

• Only http/https schemes accepted.
• Localhost and private/internal IP ranges are blocked.
• Hostname DNS resolution is validated.

Recommendation: use HTTPS endpoints with strict TLS validation and dedicated secret rotation procedures.