What is a WebHook?
The concept of a WebHook is simple. Most APIs involve a one party making a call requesting information from another party. Sometimes the request is a simple one only to confirm if the status of something has changed. Think going to a carrier’s website and entering a tracking number and checking if something was delivered. A WebHook is sometimes referred to a reverse API, where the partner with knowledge of the status change informs the other of the change. A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. With a WebHook, the carrier is telling you the package was delivered. In the WebHook, they can either tell you the status has changed allowing you to make a call for more information or provide all of the necessary data in the notification.
A web application implementing WebHooks will POST a message to a URL when certain things happen. When a web application enables users to register their own URLs, the users can then extend, customize, and integrate that application with their own custom extensions or even with other applications around the web. For the user, WebHooks are a way to receive valuable information when it happens, rather than continually polling for that data and receiving nothing valuable most of the time. WebHooks have enormous potential and are limited only by your imagination!
Why WebHook?
The WebHook reduces the load on both platforms and frees up resources for business critical applications and requests. Why have your system make routine scheduled calls for inventory availability or order status if there hasn't been a change in status? Or a user is not immediately interacting with the document? The WebHook allows you to subcribe to an event and we will alert you went there is an update.
Push: receiving data in real time
Push is the simplest of reasons to use WebHooks. As was just stated above, no more polling every couple of minutes to find out if there is new information. Just register a WebHook and receive the data at your doorstep as soon as it exists. It's less work, less hassle, and you'll probably even receive it sooner than if you were asking for it every couple of minutes.
WebHooks implement a publish/subscribe pattern where consumers (applications) can subscribe to certain events they are interested in receiving. When the event happens it acts on the event and can push a message to the consumer notifying them of the update. It provides real time updates without the constant polling or batch updates. This is the concept a carrier sending you an email or text when a tracking number was delivered.
A ScanSource business example involves a customer who is interested in knowing when an order status changes. They subscribe to the order status update notification event. The consumer provides a call back URL and other information necessary to make a call to their API. When the event occurs, an output is triggered and makes a call to the end point and sends an order status update message. The status could change from Open to Complete.
ScanSource web hooks
Scansource has implemented custom webhooks using Azure Event Grid. Azure Event Grid is deployed to maximize availability by natively spreading across multiple fault domains in every region, and across availability zones. Event grid provides durable delivery. Events are sent to subscribers immediately. If the subscriber end point does not acknowledge receipt of an event, Event Grid retries delivery of the event. Event Grid waits 30 seconds for a response after delivering a message. After 30 seconds, if the endpoint hasn’t responded, the message is queued for retry. Event Grid uses an exponential back off retry policy for event delivery. By default, Event Grid expires all events that aren't delivered within 24 hours. We can customize the retry policy as needed.
Event types
ScanSource is continuing to evolve webhooks and has implemented two custom event types.
ScanSource.SalesOrder.Status – Event is fired when an order status changes. For example, status changes from In Process to Completely Shipped
ScanSource.Product.ATP – Inventory available to promise changes.
Endpoint validation with Event Grid events
Your endpoint needs to participate in validation handshake with Event Grid. At the time of event subscription creation, Event Grid sends a subscription validation event to your endpoint. The schema of this event is similar to any other Event Grid event. The data portion of this event includes a validationCode property. Your application verifies that the validation request is for an expected event subscription, and returns the validation code in the response synchronously.
Validation details
At the time of event subscription creation/update, Event Grid posts a subscription validation event to the target endpoint.
The event contains a header value "aeg-event-type: SubscriptionValidation".
The eventType property of the event is Microsoft.EventGrid.SubscriptionValidationEvent.
The data property of the event includes a validationCode property with a randomly generated string. For example, "validationCode: acb13…".
The array contains only the validation event. Other events are sent in a separate request after you echo back the validation code.
An example SubscriptionValidationEvent is shown in the following example:
[
{
"id": "99bf9326-1be6-4823-b697-46b67b940e9b",
"topic": "/subscriptions/b3d2bd45-5b6c-47f7-90a5-de1bfe91c9a9/resourceGroups/az-p-rg-webhooks-eus-01/providers/Microsoft.EventGrid/topics/az-p-egt-atp-eus-01",
"subject": "",
"data": {
"validationCode": "48416BE1-F393-4C3D-BF04-394651361699",
"validationUrl": "https://rp-eastus.eventgrid.azure.net:553/eventsubscriptions/{yourSubscriptionName}/validate?id=48416BE1-F393-4C3D-BF04-394651361699&t=2020-11-05T16:16:45.3056626Z&apiVersion=2020-04-01-preview&token=xzlscd78ZxclliErhp53KdLSi8Z6EXglH5Mq8Mlfuvg%3d"
},
"eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
"eventTime": "2020-11-05T16:16:45.3056626Z",
"metadataVersion": "1",
"dataVersion": "2"
}
]
To prove endpoint ownership, echo back the validation code in the validationResponse property, as shown in the following example:
{
"validationResponse": "48416BE1-F393-4C3D-BF04-394651361699"
}
You must return an HTTP 200 OK response status code for a successful subscription response. The response must be within 30 seconds. If the operation doesn't finish within 30 seconds, then the operation will be canceled and it may be reattempted after 5 seconds. If all the attempts fail, then it will be treated as validation handshake error.
Delivery event formats
ScanSource.SalesOrder.Status
Example payload:
[
{
"Id": "ed66c57a-8d89-4907-afc0-8b9ece7f762a",
"Subject": "1000016536",
"EventType": "ScanSource.SalesOrder.Status",
"Data": {
"CustomerNumber": "1000016536",
"BusinessUnit": "1700",
"OrderNumber": "0016165237",
"Status": "On Hold",
"PONumber": "po123456789",
"POType": "API",
"EndUserPONumber": null,
"OrderReferenceNumber": null,
"CiscoIdentifier": null
},
"dataVersion": "",
"metadataVersion": "1",
"EventTime": "2020-11-05T21:15:32.6997917Z",
"topic": "/subscriptions/b3d2bd45-5b6c-47f7-90a5-de1bfe91c9a9/resourceGroups/az-q-rg-webhooks-eus-01/providers/Microsoft.EventGrid/topics/az-q-egt-orderstatus-eus-01"
}
]
ScanSource.Product.ATP
Example payload:
[
{
"id": "61888e8d-1ce5-4858-832c-de6481a35448",
"subject": "Product: NN3820-AC= Updated",
"data": {
"Id": "c30fbe89-bc1a-4092-898d-cf8602f1badb",
"ManufacturerPartNumber": "NN3820-AC=",
"VendorName": "ORACLE AMERICA INC",
"QuantityAvailable": 0.0
},
"eventType": "ScanSource.Product.ATP",
"dataVersion": "1.0",
"metadataVersion": "1",
"eventTime": "2020-11-18T21:46:07.8453997Z",
"topic": "/subscriptions/b3d2bd45-5b6c-47f7-90a5-de1bfe91c9a9/resourceGroups/az-q-rg-webhooks-eus-01/providers/Microsoft.EventGrid/topics/az-q-egt-atp-eus-01"
},
{
"id": "d4c7ef28-e5b9-4eaa-8942-87b9ed64fd63",
"subject": "Product: NN3820-PS-AC Updated",
"data": {
"Id": "3ef42549-1eb2-4ccc-a591-6fce031c0b12",
"ManufacturerPartNumber": "NN3820-PS-AC",
"VendorName": "ORACLE AMERICA INC",
"QuantityAvailable": 0.0
},
"eventType": "ScanSource.Product.ATP",
"dataVersion": "1.0",
"metadataVersion": "1",
"eventTime": "2020-11-18T21:46:07.8454168Z",
"topic": "/subscriptions/b3d2bd45-5b6c-47f7-90a5-de1bfe91c9a9/resourceGroups/az-q-rg-webhooks-eus-01/providers/Microsoft.EventGrid/topics/az-q-egt-atp-eus-01"
},
{
"id": "f2ec923a-efc4-4eeb-9077-8da2ba3c0c7f",
"subject": "Product: NN3820-PS-AC= Updated",
"data": {
"Id": "07afadba-de58-451e-a7ce-70b1c6bd3d7b",
"ManufacturerPartNumber": "NN3820-PS-AC=",
"VendorName": "ORACLE AMERICA INC",
"QuantityAvailable": 0.0
},
"eventType": "ScanSource.Product.ATP",
"dataVersion": "1.0",
"metadataVersion": "1",
"eventTime": "2020-11-18T21:46:07.8454186Z",
"topic": "/subscriptions/b3d2bd45-5b6c-47f7-90a5-de1bfe91c9a9/resourceGroups/az-q-rg-webhooks-eus-01/providers/Microsoft.EventGrid/topics/az-q-egt-atp-eus-01"
}
]
Success codes
Event Grid considers only the following HTTP response codes as successful deliveries. All other status codes are considered failed deliveries and will be retried or dead lettered as appropriate. Upon receiving a successful status code, Event Grid considers delivery complete.
200 OK
201 Created
202 Accepted
203 Non-Authoritative Information
204 No Content
Webhook Setup
When finished implementing the validation handshake, event payload and publishing to a public end point. Test your end point validation handshake using Postman or similar tools. Once ready, provide your endpoint to ScanSource e-business manager for subscription setup in our testing environment.
Notify b2brequest@scanource.com with your customer number, which event type (Order Status or ATP - available to promise) and contact information that you are activating a web hook so we can complete the set-up on our end.