Webhooks

This chapter describes how the Rulecube Webhooks system works, how to define webooks, and how to use webhooks to receive events from third-party systems.

Overview

Webhooks enable near-real-time notifications of events occurring in third-party systems. Instead of wendypolling those systems, many third-party systems have the possibility to register an HTTPS endpoint (a "callback URL") that will POST event payloads to that endpoint when relevant events occur.

Key principles:

• Webhooks can receive HTTPS POST, PUT or GET requests.

• Each webhook request should include a signature for verification (in header or query parameter).

• Delivered messages should include identifiers to support further processing.

• Delivered messages could contain necessary information in both headers, request parameters as well as the request body. Therefor, Rulecube supports handling all those information containers.

---

Terminology

• Event: A discrete occurrence in a third party system (e.g., order.created, payment.received, message.sent).

• Subscription: A configuration linking an event (or set of events) in the third-party system to a callback URL.

• Webhook definition: the callback URL defined in Rulecube.

• Delivery: An HTTP request made by the third party system to the Rulecube webhook containing event data.

• Delivery ID: Unique ID for each delivery to help with further processing.

---

Webhook types

Rulecube supports two distinct webhook types:

• Trigger webhooks: supports the execution of a ruleset and/or the start of a workflow using a webhook definition

• Workflow webhooks: supports the creation of a dynamic webhook from within a workflow

Trigger webhook definition

As stated above, this webhook type supports:

• the execution of a ruleset

• the start of a workflow

Workflow webhook definition

This webhook type is only available within workflows. These - short-lived - triggers are created in a workflow step and will only wait for one callback from a third-party system, e.g. a payment provider.