Webhooks

Webhooks Overview

Webhooks allow your application to receive real-time notifications when specific events occur in your Wherehouse account. When an event is triggered, our system sends a POST request to the URL you configured containing the event data.

Webhooks are useful for automatically reacting to changes such as new orders or updates to existing orders without needing to continuously poll the API.

Registering Webhooks

Webhooks can be configured in the Wherehouse dashboard:

https://app.wherehouse.co.za/settings/api-keys

Within the dashboard you can:

Add one or more destination webhook URLs

Select which event types should trigger notifications

Available Event Types

Currently the following events are supported:

ORDER_CREATED

ORDER_UPDATED

Webhook Delivery

When a subscribed event occurs, Wherehouse will send a POST request to your configured webhook endpoint with a JSON payload describing the event.

Important notes:
Webhook delivery is not guaranteed
There is currently no automatic retry mechanism if a webhook delivery fails (this may change in the future)

Because of this, we strongly recommend implementing a periodic job in your application to check for new or updated orders via the API endpoints to ensure no events are missed.

Webhook Payload Structure

Each webhook request contains the following top-level fields:

Field	Type	Description
`event_type`	string	The event that triggered the webhook
`event_timestamp`	string (ISO 8601)	Timestamp when the event occurred
`event_data`	object	The event payload data
`destination_urls`	array	The webhook endpoints configured for the event

Example Webhook Payload

Below is an example payload for an ORDER_UPDATED event.

{
  "event_type": "ORDER_UPDATED",
  "event_timestamp": "2026-03-05T14:45:38.492Z",
  "event_data": {
    "id": 918204,
    "code": "ORD-7348291",
    "status": "shipped",
    "origin_status": "Preparing for Customer",
    "order_type": "standard",
    "order_total": 1499,
    "currency_code": "ZAR",
    "date_placed": "2026-03-05T14:06:59.000Z",
    "created_at": "2026-03-05T14:42:17.480Z",
    "updated_at": "2026-03-05T14:45:38.479Z",
    "customer_first_name": "Michael",
    "customer_last_name": "Daniels",
    "customer_email": "michael.daniels@example.com",
    "shipping_address_line": "45 Market Street",
    "shipping_city": "Cape Town",
    "shipping_state": "Western Cape",
    "shipping_country": "South Africa",
    "shipping_postcode": "8001",
    "catalogue": {
      "id": 172,
      "uid": "3c2a6b7e-9c1e-41c6-8f57-82c8c0c2c9ab",
      "name": "Marketplace Feed",
      "order_count": 1842,
      "product_count": 4021,
      "created_at": "2026-02-21T11:14:09.123Z",
      "updated_at": "2026-03-05T14:30:44.890Z"
    },
    "origin_connector_type": {
      "id": 1,
      "uid": "takealot",
      "name": "Takealot",
      "logo": "https://assets.wherehouse.co.za/connectors/logos/takealot.svg"
    },
    "products_sold": [
      {
        "id": 4410021,
        "code": "SKU-AX52",
        "title": "Smart Speaker Mini - Black",
        "quantity": 1,
        "sell_price": 1499,
        "status": "shipped",
        "product": {
          "id": 201994,
          "code": "SKU-AX52",
          "title": "Smart Speaker Mini - Black",
          "retail_price": 1899,
          "sale_price": 1499,
          "weight_g": 480,
          "length_cm": 16,
          "width_cm": 10,
          "height_cm": 9,
          "main_image": "https://cdn.example.com/products/speaker-mini.jpg"
        },
        "created_at": "2026-03-05T14:42:17.485Z",
        "updated_at": "2026-03-05T14:45:27.972Z"
      }
    ]
  },
  "destination_urls": [
    "https://example-webhook-endpoint.com/webhooks/orders"
  ]
}

Handling Webhooks

Your webhook endpoint should:

Accept POST requests

Parse the JSON request body

Return a 200 response quickly to acknowledge receipt

If your endpoint does not return a successful response, the webhook delivery will be considered failed.

Best Practices

Respond to webhook requests as quickly as possible

Process heavy logic asynchronously (e.g. queue a background job)

Implement periodic API polling to ensure missed events are recovered

Log webhook payloads for debugging and replay purposes

Webhooks Overview#

Registering Webhooks#

Available Event Types#

Webhook Delivery#

Webhook Payload Structure#

Example Webhook Payload#

Handling Webhooks#

Best Practices#