1. WebHooks

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 an integrated assortment.

If your integration already supports the integrated assortment 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.

Webhooks are normally the preferred method of integrating orders because it's the simplest solution and the orders will be posted to the configured endpoint at the same moment it's sent in our platform. The only drawback is the security is less robust.

The advantages of using this approach is:

1. Simplicity. The only thing required on your side is to develop the endpoint linked to the webhook to process the order and return an appropriated HTTP status code.
2. The orders are immediately sent to the configured endpoint as soon as the order is placed on Apicbase platform.
3. Orders placed on our platform and rejected by the webhook endpoint (any response code different than 2XX) will immediately display an error to the customer at the end of the process. The customer must place the order again manually to complete the process, which avoids the need of contacting the customer about orders that can't be fulfilled. That's useful specially for orders with the HTTP response status code 4XX.

However, please be aware of the drawbacks:

1. The security is less robust than using the API endpoint.
2. Orders rejected by the webhook due to issues in the endpoint server (e.g. bugs, server unavailable), .i.e. 5XX error codes, are not retried automatically. That means the customer will not be able to place the order while the issue is not fixed.

Please note that failing orders due to errors either on our side or on the webhook's endpoint (any response code different than 2XX) will result on an error message to be displayed to the customer. The order status will remain as in progress (i.e. not sent) and the customer will have to retry sending it manually after the issue is fixed. So it's important to understand that failed orders will not be automatically retried and will not be in a state between in progress and sent.

1.1. 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)

1.2. Testing

The orders can be tested as soon as the following things are done on our side:

1. You have access to a test account setup for you on our platform.
2. Some articles were loaded in your account through the create assortment file endpoint.
3. The URL which our webhook should send orders is set on our side.

Once all of the above is done, please follow this support article to understand how the customer place orders on our platform. You can reproduce it to place an order yourself that will trigger the webhook and send the order to your system.

2. API Endpoint

Using our API is an alternative to the webhook approach. The response JSON is the same as the webhook one and more information about it can be found in the endpoint reference.

We recommend using it if one or more of the points below are applicable:

1. There's more flexibility about when to process orders placed by the customer (instead of processing it immediately).
2. You need a more robust security. The API endpoint will follow our standard OAuth2 authentication.
3. Avoid rejecting orders due to errors on your side. As mentioned in the webhook section, orders placed by the customer will fail if we receive any error (any response code different than 2XX) from the webhook endpoint. Therefore the API is useful for 5XX errors, since the orders can be processed later retroactively once the issue is fixed.

However, please be aware of the drawbacks:

1. This approach is more complex when compared to the webhook because you must:
   1. Keep track of which orders were already processed from our list endpoint;
   2. Periodically call our API endpoint to get new orders, taking into account our rate limits.
2. When a customer places an order in Apicbase, its status will be updated immediately to ORDERED (i.e. sent to the suppler) and this status can't be reverted. However, the webhook approach only updates the order status after getting a successful response from the linked endpoint. That means it's not possible run any validation before the order status is updated in the API approach. Thus invalid orders that are later rejected when our API is consumed should be communicated directly to the customer.