Tutorial: Creating a Simple Webhook

A Webhook is an asynchronous HTTPS callback to an external server to notify it of events that the external party is interested in. The external party that is interested in receiving the notification will implement an end-point to receive the JSON based notifications as they occur. Since webhooks are an outbound process from UltraCart to the external party they happen quicker and are far more efficient than polling an API.

All Webhooks are associated with a Resource API such as "item" and are triggered for a defined set of events that the receiver has subscribed to. Each resource will describe the webhooks that are available to subscribe to, the REST model that is delivered in the notification as well as the expansion operations that are also allowed.

For security purposes, we always recommend that your Webhook endpoint URLs be secured with HTTPS. This is not a requirement for certain resource types, such as items, but it is required whenever any customer information is transmitted to your server.

UltraCart expects that integrations will respond within thirty seconds of receiving the webhook payload. Therefore you should favor asynchronous processing of the payload vs synchronous processing whenever possible. By receiving the payload and queuing it so that all the "real work" happens in a background job, you ensure fast response times for the webhook delivery and buffering of your server against a large amount of notices. There are various ways to queue background jobs depending upon your language such as writing the webhook payload to a database table and then processing in a scheduled job or utilizing a message queueing libraries such as Resque (for Ruby), RQ (for Python), or RabbitMQ (for Java) for example. When configuring the Webhook, there are optional limits on the number of event notifications that can be bundled together, the minimum is 10, and the maximum size of the payload (900K/message maximum). The maximum limits allow for further tuning of the amount of work that is delivered to your server per HTTPS POST.

UltraCart currently makes a single concurrent notification at a time to each of the Webhook endpoints. Notifications generally are delivered in and oldest to newest order. All webhooks receive a fair shot of delivery of their notifications each processing cycle. So if one merchant generates a lot of notifications (through an item import for example), the system will make sure that their notification workload does not adversely impact the delivery of notifications for other merchants.

If your server goes down for a brief period of time, UltraCart will queue up the pending notifications and retry them. If your server encounters errors or down time for an extended period of time, UltraCart will begin discarding the older notifications in the queue as newer ones arrive until ultimately the webhook is disabled.

For consistency, each Webhook configuration will determine the API version that the notifications should conform to. By versioning the outbound webhook notices in the same fashion as the inbound API calls, we can guarantee more stability in the API. It also allows you to parse the webhook JSON that you receive into an SDK object.

While UltraCart strives for very fast delivery of Webhook notifications, there are no guarantees on the time frame between the triggering of the event and the actual delivery of the notification. It can be as short as a few milliseconds at times, but you should not build any business workflow that is critically dependant upon the speed of webhook delivery.

If you're still wondering about the importance of Webhooks, look at a real-world example of their use in the Wordpress plugin. When the plugin is first authorized via OAuth 2.0 authentication, it sets up a webhook with three item events (item_create, item_update, and item_delete) so that all changes to the item information are quickly conveyed to the wordpress instance. After the webhook is created, the plugin makes another API call asking UltraCart to reflow all item_update events. UltraCart in an asynchronous and controlled fashion resends all the existing items from the UltraCart account to the wordpress plugin's webhook endpoint. Two API calls setup and trigger the entire process and no polling is required after that point.