To facilitate the process of integrated ordering, Apicbase supports setting up webhooks that allow the platform to post orders created by customers directly to suppliers. A prerequisite for setting up the integrated ordering is to set up the integrated assortment sync.

If your integration already supports the assortment sync and you would like to set up integrated ordering via webhooks, contact [email protected] with the URL of the HTTP/S endpoint that orders should be posted to, and we'll set it up for you.

Purchase Order Structure

The purchase order object that will be sent to the webhook you've set up has the following structure:

{
  "id": string, -> Apicbase internal Purchase Order ID
  "order_number": string,
  "status": "ORDERED", -> fixed value
  "ordered_on": datetime,
  "owned_by": {"username": string} | null,
  "order_remarks": string | null,
  "packages": [
    {
      "stock_item": {
        "name": string
      },
      "supplier_package": {
        "supplier_article_number": string,
        "theoretical_price_per_package": string
      },
      "quantity_ordered": integer,
      "total_theoretical_price": string
    }
  ],
  "expected_delivery_date": datetime | null,
  "theoretical_price": string,
  "supplier_customer_number": string
}

❗️

A note about security.

To ensure the security of these requests, each request from Apicbase is signed with an X-APIC-WEBHOOK-SIGNATURE header key. It is highly recommended that the supplier uses this value to verify if the payload being received is indeed sent by Apicbase.

This verification requires using the client secret and the received payload to generate a HMAC-SHA256 Hexdigest value.

By default, the client secret value is the same one used to generate new tokens, but it's also possible to use a different unique key that is only used to encode this header. Just let us know and we can arrange this for you.

Here's a code snippet with some sample Python code that validates the signature header:

Python

import json
from hmac import HMAC

def endpoint(request):
    signature = request.headers["X-APIC-WEBHOOK-SIGNATURE"]
    
    result = HMAC(
        key="<your_client_secret>",
        msg=json.dumps(request.data).encode(),
        digestmod="sha256"
    ).hexdigest()
    
    if signature != result:
        return Response("Incorrect signature", status_code=403)