Skip to main content
Explanation

Webhooks

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 wants to receive the notification implements an endpoint 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 describes 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 allowed.

warning

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.

Responding to notifications​

UltraCart expects that integrations will respond within thirty seconds of receiving the webhook payload. Therefore you should favor asynchronous processing of the payload over 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 buffer 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 it in a scheduled job, or utilizing a message-queueing library such as Resque (for Ruby), RQ (for Python), or RabbitMQ (for Java). 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.

Delivery, ordering, and fairness​

UltraCart currently makes a single concurrent notification at a time to each of the webhook endpoints. Notifications are generally delivered in oldest-to-newest order. All webhooks receive a fair shot at delivery of their notifications each processing cycle. So if one merchant generates a lot of notifications (through an item import, for example), the system makes 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 downtime 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.

note

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 dependent upon the speed of webhook delivery.

Versioning​

For consistency, each webhook configuration determines 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. See Versioning for more.

A real-world example​

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 set up and trigger the entire process, and no polling is required after that point.

tip

Looking to create and manage webhook subscriptions programmatically? See the Webhooks endpoints in the API reference.

Was this page helpful?