Guide to Managing Webhooks in the External System for Stock & Trace

The following guide is for the technical teams of the external system connected to Stock & Trace.

This article covers the following topics:

• Confirming the authenticity of messages from Stock & Trace
• Communicating error messages in a webhook transaction

Other related articles:

• Explanation of Communication via Webhooks

Confirming the authenticity of messages from Stock & Trace

To ensure the authenticity of the messages that the external system receives from Stock & Trace, it is essential to authenticate that they truly come from Stock & Trace. The messages are sent via HTTP POST requests in JSON format.

Essential criteria:

• A Stock & Trace super administrator must configure the webhook and provide the related secret code for authenticity.

Steps to validate that the communication comes from Stock & Trace:

1. Perform a Hash of the content of the received HTTP body from Stock & Trace, using HMAC with the SHA256 algorithm.
2. Use the provided secret code to generate the HMAC.
3. Compare the HMAC result with the value in the HTTP header X-StockAndTrace-Signature of the original message. If they do not match, do not trust the received request.

Communicating error messages in a webhook transaction

Stock & Trace offers an API so that the external system can report on errors that prevented the information from being processed correctly in its system. This allows the warehouse team to have visibility into possible problems that affect the process.

Examples of errors that can be communicated:

• The external system does not accept requests from Stock & Trace due to changes in its infrastructure or technical problems.
• Failures in order processing caused by invalid information transmitted from Stock & Trace.

Criteria for communicating an error message:

• The external system needs to extract the transaction ID from the message received via the webhook.

Steps to communicate an error message:

• Upon receiving a message via webhook from Stock & Trace, extract the transaction ID, which is found under transaction.id.
• Use the endpoint POST api/v1/external_integrations/transaction/{id}/errors, replacing {id} with the unique transaction identifier received from Stock & Trace.
• In the body of the request, send an array with the different errors found when validating the information in your system.
  • For more detail on the structure expected by the API, consult the "Webhook - Add errors" message in the following Postman collection.