diff --git a/docs/README.md b/docs/README.md index 8013fc0..29c679e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,21 @@ +--- +coverY: 0 +layout: + cover: + visible: true + size: full + title: + visible: true + description: + visible: true + tableOfContents: + visible: false + outline: + visible: false + pagination: + visible: true +--- + # Deveel Webhooks Here you can find documentation of the `Deveel Webhooks` framework, to help you get started with the libraries and functions that compose it and to understand how it works. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index de138ea..dc66b04 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -4,7 +4,10 @@ * [Getting Started](getting-started.md) * [Concepts](concepts/README.md) * [What is a Webhook?](concepts/webhook.md) - * [What is a Webhook Subscription?](concepts/webook\_subscription.md) + * [What is a Webhook Subscription?](concepts/webook-subscription.md) + * [What is a Sender of Webhooks?](concepts/webhook-sender.md) + * [What is a Receiver of Webhooks?](concepts/webhooks-receivers.md) + * [What is an Event Notification?](concepts/webhook-notification.md) * [Sending Webhooks](send\_webhooks/README.md) * [Configuring the Sender](send\_webhooks/configuring-the-sender.md) * [Signing Webhooks](send\_webhooks/signing-webhooks.md) diff --git a/docs/concepts/README.md b/docs/concepts/README.md index f14a1cf..1f9f93a 100644 --- a/docs/concepts/README.md +++ b/docs/concepts/README.md @@ -2,10 +2,10 @@ The following concepts are used in this project: -| Topic | Description | -| ------- | ------------- | -| **[Webhook](webhook.md)** | What is it a 'Webhook' and why I need it? | -| **[Subscriptions](webhook_subscription.md)** | How does a subscription to an event works? | -| **[Senders](webhook_sender.md)** | What is a sender of webooks? | -| **[Receivers](webhook_receiver.md)** | What is a receiver of webooks? | -| **[Notifications](webhook_notification.md)** | What is a notification of events? | +| Topic | Description | +| --------------------------------------------- | ------------------------------------------ | +| [**Webhook**](webhook.md) | What is it a 'Webhook' and why I need it? | +| [**Subscriptions**](webhook\_subscription.md) | How does a subscription to an event works? | +| [**Senders**](webhook-sender.md) | What is a sender of webooks? | +| [**Receivers**](webhook-sender.md) | What is a receiver of webooks? | +| **Notifications** | What is a notification of events? | diff --git a/docs/concepts/webhook-notification.md b/docs/concepts/webhook-notification.md new file mode 100644 index 0000000..7676a20 --- /dev/null +++ b/docs/concepts/webhook-notification.md @@ -0,0 +1,2 @@ +# What is an Event Notification? + diff --git a/docs/concepts/webhook-sender.md b/docs/concepts/webhook-sender.md new file mode 100644 index 0000000..1d8503c --- /dev/null +++ b/docs/concepts/webhook-sender.md @@ -0,0 +1,38 @@ +--- +layout: + title: + visible: true + description: + visible: false + tableOfContents: + visible: false + outline: + visible: true + pagination: + visible: true +--- + +# What is a Sender of Webhooks? + +Considering the overall network of communications, where Webhooks are messages exchanged between two applications, a Webhook Sender is an application that sends these messages to another application (or to a multitude of applications). + +In real life, you might consider the _Sender_ as the postman delivering a letter or a package to the destination, ensuring the address is correct and exists, that the postbox can hold the shipment, eventually coming back more than once at the address (if the recipient is not at home), accepting the signature, etc. + +As much as a postman wouldn't care if the letter or package was in delivery because of an agreement between the recipient and an organization, the same way a Webhook Sender doesn't have to necessarily require the knowledge that an application is expecting the message it is sending (this would be a [Webhook Subscription](webook-subscription.md)). + +### The Delivery Destination + +A Sender requires the specification of a Destination, to be able to attempt the delivery of Webhooks, which is like a postal address, following the example above. + +In most cases, this is simply a URL (_Universal Resource Locator_), that can be reached by an HTTP request, but in some scenarios, this can be enriched with further information instructing the sender on the behavior to have with it, when attempting to deliver a package (for example, we inform the sender to leave the package to our neighbor, if we are not at home, or to try reaching us only on Thursdays, etc.). + +Such destination-specific instructions would act as an exception to the regular behavior of the sender, which is described below. + +### The Sender Behavior + +When sending a Webhook to another party, the application sending messages should ensure that the destination is reachable, the message is well-formatted, its delivery is retried (in case of failures), and the integrity of the content is assured. + +This is done by a configured behavior, that typically provides the following elements of configuration + +
AttributeDescription
Content TypeThe specification of the format of the contents of the Webhook message (eg. JSON, XML, Form-Encoded)
Retry StrategyThe methodology to deliver the message (eg. Circuit Breaker, Exponential Backoff, Timeout, etc.), and the configurations of retries (eg. a maximum number of retries, delays between attempts, etc.)
Signature MethodA methodology used to sign the Webhook payloads, so that the the receiver can ensure their integrity
ContextThe set of contextual information informing the receiver of the origination of the Webhook (eg. the machine name, the application type, etc.)
+ diff --git a/docs/concepts/webhooks-receivers.md b/docs/concepts/webhooks-receivers.md new file mode 100644 index 0000000..65ebd97 --- /dev/null +++ b/docs/concepts/webhooks-receivers.md @@ -0,0 +1,10 @@ +# What is a Receiver of Webhooks? + +As we have cleared out before, Webhooks are messages that inform an application of the occurrence of an event in a system: as such we consider the context of communications, where there are two (or more) parties sending and receiving messages between each other. + +In a specular way to the definition of the Webhook Sender, of which we made an analogy with a postman delivering a letter or a package, the Webhook Receiver can be considered the recipient (a person or a company), that physically receives the deliverable. + +Considering the real-life scenario of delivery of letters or packages, we all can be receivers, if we provide a postbox with our name on it, that we make available for postmen to access. + +In some special cases of secure shipments, we might also be requested to sign a receipt to ensure that the packages or envelopes were actually delivered. + diff --git a/docs/concepts/webook_subscription.md b/docs/concepts/webook-subscription.md similarity index 59% rename from docs/concepts/webook_subscription.md rename to docs/concepts/webook-subscription.md index c9caaee..45fdbde 100644 --- a/docs/concepts/webook_subscription.md +++ b/docs/concepts/webook-subscription.md @@ -1,29 +1,14 @@ - - # What is a Webhook Subscription? It is easy to define the concept of subscription to the notification of a certain type of events, and we have several examples of this in our daily life: -* We can subscribe to a newspaper to receive it every day, + +* We can subscribe to a newspaper to receive it every day, * We can be opt-in to be notified when a new product is available in a shop by a phone call or an email * We can subscribe to a newsletter to be notified when a new article is published on a blog In all these cases, we are interested in being notified when something happens, and we are not interested in the details of the event itself: some of the elements of the event are relevant to us, and some of these elements are relevant for the publisher to know how and when to reach us. -For the other party that has to notify us on the type of events we are interested in, it is important to know how to reach us, and it is important to know what we are interested in. +For the other party that has to notify us on the type of events we are interested in, it is important to know how to reach us, and it is important to know what we are interested in. In the case of a newspaper, the publisher needs to know our address, and the type of newspaper we want to receive. In the case of a shop, the publisher needs to know our phone number or email address, and the type of products we are interested in. In the case of a blog, the publisher needs to know our email address, and the type of articles we are interested in. @@ -39,11 +24,15 @@ Subscriptions to events are typically indicating used by publisher to control th Although no formal specification for this type of objects was agreed and standardized, a typical pattern across the providers of services is to define the following elements: -* **Subscription ID**: a unique identifier of the subscription, used to identify the subscription in the system -* **Subscription Name**: a human-readable name of the subscription, used to identify the subscription in the system -* **Event Type**: the type of event the subscription is interested in -* **Event Criteria**: a set of criteria that the event must satisfy in order to be notified to the subscriber -* **Endpoint**: the endpoint where the subscriber will be notified of the event -* **Status**: the status of the subscription, which can be `ACTIVE`, `INACTIVE`, `EXPIRED`, `DELETED` -* **Headers**: a set of headers that will be sent to the subscriber when the event occurs (usefull to identify a context) -* **Secret Key**: a secret key that will be used to sign the notification to the subscriber \ No newline at end of file + + +| Attribute | Description | +| ------------------------ | ---------------------------------------------------------------------------------------------------------- | +| **Subscription ID** | A unique identifier of the subscription, used to identify the subscription in the system | +| **Subscription Name** | A human-readable name of the subscription, used to identify the subscription in the system | +| **Event Type** | The type of event the subscription is interested in | +| **Event Criteria** | A set of criteria that the event must satisfy in order to be notified to the subscriber | +| **Destination Endpoint** | The endpoint where the subscriber will be notified of the event | +| **Status** | The status of the subscription, which can be `ACTIVE`, `INACTIVE`, `EXPIRED`, `DELETED` | +| **Headers** | A set of headers that will be sent to the subscriber when the event occurs (usefull to identify a context) | +| **Secret Key** | A secret key that will be used to sign the notification to the subscriber |