📚 Add integration guide with webhooks

technical-guide/getting-started.md

@@ -1,8 +1,8 @@
 ---
-title: 1. Self-hosting guide
+title: 1. Self-hosting Guide
 ---
 
-# Self-hosting guide
+# Self-hosting Guide
 
 This guide explains how to get your own Penpot instance, running on a machine you control, to test it, use it by you or your team, or even customize and extend it any way you like.
 

technical-guide/index.md

@@ -6,7 +6,7 @@ eleventyNavigation:
 ---
 
 <div class="main-illus">
-  <img src="/img/home-techguide.png" alt="Technical guide" border="0">
+  <img src="/img/home-techguide.png" alt="Technical Guide" border="0">
 </div>
 
 # Technical Guide
@@ -24,13 +24,18 @@ machine.
 
 * Or you can try other, not supported by Penpot, [Unofficial options][4].
 
+## Integration with external apps
+
+The [Integration Guide][5] explains how to connect Penpot with external apps, so they get notified
+when certain events occur and may create your own interconnections and collaboration features.
 ## Developing Penpot
 
 Also, if you are a developer, you can get into the code, to explore it, learn how it is made, or extend it and contribute with new functionality. For this, we have a different Docker installation.
-In the [Developer Guide][5] you can find how to setup a development environment and many other dev-oriented documentation.
+In the [Developer Guide][6] you can find how to setup a development environment and many other dev-oriented documentation.
 
 [1]: /technical-guide/getting-started/#install-with-elestio
 [2]: /technical-guide/getting-started/#install-with-docker
 [3]: /technical-guide/configuration/
 [4]: /technical-guide/getting-started/#unofficial-self-host-options
-[5]: /technical-guide/developer/
+[5]: /technical-guide/integration/
+[6]: /technical-guide/developer/

technical-guide/integration.md

@@ -0,0 +1,55 @@
+---
+title: 4. Integration Guide
+---
+
+# Integration Guide
+
+This section explains how to interconnect Penpot with other applications, so
+they can collaborate and create new kinds of features, or integrate in DesignOps
+or GitOps workflows.
+
+The system is relatively simple for now, but expect more functions in the future.
+
+## Webhooks
+
+Outbound webhooks are event calls from Penpot to other applications, that
+notifiy some particular event has occured (e.g. a file has been created or
+updated, a comment has been added, etc.).
+
+In Penpot, webhooks are configured at Team level:
+
+![Add a webhook](/img/webhooks.png)
+
+When you add a webhook, you specify the URL of a service you own. If the webhook
+is active, the URL will be called on any event that occurs anywhere in the team.
+
+You can specify the format of the call payload.
+
+* JSON is a standard format, accepted by almost every web application.
+* <a href="https://github.com/cognitect/transit-format" target="_blank">Transit</a>
+is a format, that may be encapsulated inside JSON, that adds datatype
+information and enriches the content with semantic information.
+
+### Events list
+
+Unfortunately, we still have not a separated documentation for the webhook events.
+For the moment you can use the <a href="https://design.penpot.app/api/_doc"
+target="_blank">backend API documentation</a>, generated automatically from <a
+href="https://github.com/penpot/penpot/tree/main/backend/src/app/rpc"
+target="_blank">source code</a>, as a guide.
+
+All backend RPC calls labelled as `WEBHOOK` trigger webhook calls, if
+appropriate, with an equivalent payload.
+
+The payload content is specified as <a href="https://clojure.org/guides/spec"
+target="_blank">Clojure Spec</a> predicates:
+
+![Example of a RPC call](/img/webhook-call.png)
+
+The listed spec details all required (`:req` or `:req-un`) and optional
+(`:opt-un`) attributes of the RPC parameters.
+
+The payload of the webhook is similar, but there may be some changes (some
+parameters ommited or others added). The recommended way of understanding the
+webhook calls is by using <a href="https://webhook.site/" target="_blank">Webhook.site</a>.
+Generate a site URL and set it into Penpot. Then you can inspect the calls received.