Rulecube Documentation

Appearance

v2.7 (latest)
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.

Webhooks ​

This section provides step-by-step instructions for configuring and using webhooks in Rulecube.

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.

Use the following guides to complete tasks related to webhooks: