mirror of
https://github.com/penpot/penpot-docs.git
synced 2024-07-12 06:41:46 +00:00
📚 Add integration guide with webhooks
This commit is contained in:
parent
028c70a84a
commit
e924273ab3
BIN
img/webhook-call.png
Normal file
BIN
img/webhook-call.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 35 KiB |
BIN
img/webhooks.png
Normal file
BIN
img/webhooks.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 53 KiB |
|
@ -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.
|
||||
|
||||
|
|
|
@ -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/
|
||||
|
|
55
technical-guide/integration.md
Normal file
55
technical-guide/integration.md
Normal file
|
@ -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.
|
Loading…
Reference in New Issue
Block a user