Webhooks are a useful device to have in a REST API toolkit because they allow a connected application to be notified instantly when a relevant piece of data is changed. If the REST API doesn’t have this function, then the App must poll the database at a set interval or as part of the relevant steps to ensure that an event has or hasn’t occurred.

Zapier, through their Rest Hooks website have stated that Apps run 66 times faster with webhooks and that on average 98.5 % of polling is wasted.

From Jiwa’s point of view, webhooks are a way of integrating Jiwa with other 3rd party API’s. 

When an event in Jiwa occurs (such as when a product is created), the 3rd party API can be notified instantly using webhooks.

Webhooks eliminate the need for polling, which can be inefficient and introduce latency between the event occurrence and when an action in response to that event occurs.

How have we implemented this?

Webhooks in Jiwa are implemented by augmenting the existing REST API with webhook functionality via a plugin.  It is based on a subscriber/subscription model.

  • Subscribers are defined in Jiwa, and a subscriber once given their SubscriberID can register a subscription to the possible webhooks available in Jiwa. 
  • When events occur in Jiwa, a message is generated and sent to the webhook subscriptions. The result of that message is then stored in a message response.  Messages which fail to be sent to a subscriber are queued for retry based on some system settings.

    To make webhooks easier to set up we have made our webhooks subscription based.

    Subscribers can also remove their own subscriptions and inspect what messages have been sent or attempted to be sent and the status of the message.

    All webhook messages are sent as a POST operation with any relevant document as the body.


    Message Retries & Resilience

    Webhook messages are sent to subscribers as they occur in Jiwa immediately and asynchronously – meaning it happens in the background and the time taken to send the message does not delay or impact users of Jiwa.

    If a message should fail, then it is retried based on a time schedule.  All messages are sent by the REST API service, not the Jiwa clients themselves – so the Jiwa client that originally generated the webhook event does not need to remain powered on.

    Where is it stored in Jiwa?

    Inside Jiwa, messages are persisted to a SQL Table SY_WebhookMessage, and that table is read when the REST API Service starts and unsent messages are queued for delivery. By default, messages are re-tried after 1 second, then 10 seconds, 100 seconds, and so on until after the 6th retry, the message is marked as failed (Status 3) and no longer retried.

    System settings under the “REST API Webhooks” tab of the system configuration form control how long the retry interval is, and the maximum number of retries to attempt.

    This strategy of persisting the messages to an SQL table and retrying delivery of failed messages at growing intervals provides the resilience required to integrate with another API’s.

    Zapier and others are talking about Webhooks and have coined the term Rest Hooks. Rest Hooks have a website that adds to this blog article, check it out for more information. Jiwa’s documentation is available here.