Webhook communications

Webhooks are a modern mechanism used to notify external SaaS services or partner systems on the outcome of asynchronous actions, completed at a later time and not directly in response to a previous/synchronous request.

For example, a vendor may register their interest to receive an update when your warehouse receives goods, they dispatched in response to a purchase order. You can use a mix of Neptune DXP apps and microservices combining synchronous and asynchronous communications to engineer updates to your suppliers. To implement this, a Neptune DXP "Vendor Collaboration" app is needed as an input console for your vendors to register their interest for such updates, along with a Neptune DXP webhook delivery microservice acting as an aggregation mechanism collecting such requests and associating them with events published to an enterprise event stream that can satisfy it.

In this case the Neptune DXP webhook service implementation subscribes to a "Goods Received" event issued by another Neptune DXP microservice acting as a proxy service to your "Commercial off the Shelf" (COTS) warehouse management system. Once the event is received and processed the webhook microservice proceeds with ansynchronous API request (typically using a POST method), which includes the update.

webhook1

Below is a narrative of the indicative steps that take place to register, process and deliver a webhook using Neptune DXP components:

  1. Webhook request a Neptune DXP web app used as an input console by your vendors to register their interest to receive direct updates. The app must list the following key parameters used to build an effective and secure architecture:

    1. Required event selected by the vendor to identify the event they are interested to receive an update on, in this case, "Goods Received".

    2. HTTP endpoint (IP Address/port) where the Neptune DXP webhook service will post the update.

    3. Recipient signature a secret unique key (for example a UUID) generated by Neptune DXP to be included in the header of each webhook update. As this will be unknown to malicious agents the vendor can use the signature to confirm the origin of a webhook update.

    4. HTTP authentication for Neptune DXP to use when connecting to the vendor’s HTTP endpoint.

    5. Offline retrieval option to provide in the webhook upload an ID pointing to the "Goods Received" event rather than the payload itself. This allows vendors to optionally retrieve the update if they wish to via a subsequent API request. This can be useful when a sampling strategy is implemented to process only a portion of the updates, for example, 5% allowing for a minimal traffic footprint.

  2. Webhook registration once the vendor submits their webhook request the Neptune DXP "Webhook Console" app registers the request with a dedicated "Neptune DXP Webhook Delivery" microservice recording it in a private database table.

  3. Event subscription the "Neptune DXP Webhook Delivery" microservice will next subscribe to the "Goods Received" event carried by the event Stream i.e. a message bus operating on a publish/subscribe basis to process asynchronous events between microservices. A pre-requisite to this step would have the registration of the "Goods Receipt" event by the Neptune DXP WMS proxy microservice with the event bus.

  4. SAP "Good Receipt" posted the SAP WMS system triggers a goods receipt into the warehouse. An SAP user-exit or periodic job triggers an API POST method generated with the Neptune DXP SAP connector to update the Neptune DXP WMS proxy microservice.

  5. Publish "Goods Receipt" event. The proxy WMS service will in turn process the API request triggered by SAP to formulate a new event and then publish it to the event Stream for any potential subscribers to act on it.

  6. Receive "Goods Receipt" event as the Neptune DXP "Webhook Delivery" service is a subscriber to this event it will consume, store it and match it against the vendor that have registered their interest to receive a direct update.

  7. Post "Goods Receipt" Webhook the Neptune DXP "Webhook Delivery" service initiates an HTTP POST update to the endpoint provided by the supplier.

If an offline retrieval mechanism is implemented two additional requests would be necessary. One from the supplier requests the body of the update and another one from the webhook delivery service to provide the payload. However, you may consider delegating this task to dedicated microservice to lighten the load on the webhook delivery service.

The above example can be easily adapted to serve a multitude of webhook use cases, such as:

  • Customer fulfilment track & trace updates

  • Payment confirmations or rejections

  • IoT exception events, in addition to regular telemetry streams, for example updating on failures