mirror of
https://github.com/matrix-org/matrix-hookshot.git
synced 2025-03-10 21:19:13 +00:00
parent
8b31a4bfe8
commit
b491ad1e07
1
changelog.d/401.doc
Normal file
1
changelog.d/401.doc
Normal file
@ -0,0 +1 @@
|
||||
Correct some typos in documentation pages.
|
@ -54,9 +54,9 @@ This can be enabled by setting `roomSetupWidget` to an object. You can add the w
|
||||
When `addOnInvite` is true, the bridge will add a widget to rooms when the bot is invited, and the room has **no existing connections**.
|
||||
|
||||
`disallowedIpRanges` describes which IP ranges should be disallowed when resolving homeserver IP addresses (for security reasons).
|
||||
Unless you know what you are doing, it is recommended to not include this key. The default blocked IPs are listed above for your convienence.
|
||||
Unless you know what you are doing, it is recommended to not include this key. The default blocked IPs are listed above for your convenience.
|
||||
|
||||
`publicUrl` should be set to the publically reachable address for the widget `public` content. By default, hookshot hosts this content on the
|
||||
`publicUrl` should be set to the publicly reachable address for the widget `public` content. By default, hookshot hosts this content on the
|
||||
`widgets` listener under `/widgetapi/v1/static`.
|
||||
|
||||
`branding` allows you to change the strings used for various bits of widget UI. At the moment you can:
|
||||
@ -65,8 +65,8 @@ Unless you know what you are doing, it is recommended to not include this key. T
|
||||
`openIdOverrides` allows you to configure the correct federation endpoints for a given set of Matrix server names. This is useful if you are
|
||||
testing/developing hookshot in a local dev environment. Production environments should not use this configuration (as their Matrix server name
|
||||
should be resolvable). The config takes a mapping of Matrix server name => base path for federation.
|
||||
E.g. if your server name was `my-local-server` and you federation was readable via http://localhost/_matrix/federation,
|
||||
you would put configure `my-local-server: "http://localhost`.
|
||||
E.g. if your server name was `my-local-server` and your federation was readable via http://localhost/_matrix/federation,
|
||||
you would put configure `my-local-server: "http://localhost"`.
|
||||
|
||||
In addition to setting up the widgets config, you must bind a listener for the widgets resource in your `listeners` config.
|
||||
|
||||
@ -82,7 +82,7 @@ See the [setup page](../setup#listeners-configuration) for more information on l
|
||||
|
||||
### API
|
||||
|
||||
The API for widgets is currently in flux due to being fairly new, and it's not reccomended
|
||||
The API for widgets is currently in flux due to being fairly new, and it's not recommended
|
||||
to develop against it at this time. At a future date this API will be merged with the existing
|
||||
provisioning API and the details will be published.
|
||||
|
||||
|
@ -51,7 +51,7 @@ Where `/etc/matrix-hookshot` would contain the configuration files `config.yml`
|
||||
## Configuration
|
||||
|
||||
Copy the `config.sample.yml` to a new file `config.yml`. The sample config is also hosted
|
||||
[here](./setup/sample-configuration.md) for your convienence.
|
||||
[here](./setup/sample-configuration.md) for your convenience.
|
||||
|
||||
You should read and fill this in as the bridge will not start without a complete config.
|
||||
|
||||
@ -117,7 +117,7 @@ The `level` can be:
|
||||
|
||||
When permissions are checked, if a user matches any of the permission set and one
|
||||
of those grants the right level for a service, they are allowed access. If none of the
|
||||
definitions match, they are denined.
|
||||
definitions match, they are denied.
|
||||
|
||||
#### Example
|
||||
|
||||
@ -125,7 +125,7 @@ A typical setup might be.
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
# Allo all users to send commands to existing services
|
||||
# Allow all users to send commands to existing services
|
||||
- actor: *
|
||||
services:
|
||||
- service: *
|
||||
@ -184,8 +184,8 @@ At a minimum, you should bind the `webhooks` resource to a port and address. You
|
||||
port, or one on each. Each listener MUST listen on a unique port.
|
||||
|
||||
You will also need to make this port accessible to the internet so services like GitHub can reach the bridge. It
|
||||
is recommended to factor hookshot into your load balancer configuration, but currrently this process is left as an
|
||||
excercise to the user.
|
||||
is recommended to factor hookshot into your load balancer configuration, but currently this process is left as an
|
||||
exercise to the user.
|
||||
|
||||
In terms of API endpoints:
|
||||
|
||||
@ -196,7 +196,7 @@ In terms of API endpoints:
|
||||
- The `widgets` resource handles resources under `/widgetapi/v1...`. This may only be bound to **one** listener at present.
|
||||
|
||||
<section class="notice">
|
||||
Please note that the appservice HTTP listener is configured <strong>seperately</strong> from the rest of the bridge (in the `homeserver` section) due to lack of support
|
||||
Please note that the appservice HTTP listener is configured <strong>separately</strong> from the rest of the bridge (in the `homeserver` section) due to lack of support
|
||||
in the upstream library. See <a href="https://github.com/turt2live/matrix-bot-sdk/issues/191">this issue</a> for details.
|
||||
</section>
|
||||
|
||||
|
@ -78,7 +78,7 @@ If the body does NOT contain a `text` field, the full JSON payload will be sent
|
||||
### GET requests
|
||||
|
||||
In previous versions of hookshot, it would also handle the `GET` HTTP method. This was disabled due to concerns that it was too easy for the webhook to be
|
||||
inadvetently triggered by URL preview features in clients and servers. If you still need this functionality, you can enable it in the config.
|
||||
inadvertently triggered by URL preview features in clients and servers. If you still need this functionality, you can enable it in the config.
|
||||
|
||||
Hookshot will insert the full content of the body into a key under the Matrix event called `uk.half-shot.hookshot.webhook_data`, which may be useful if you have
|
||||
other integrations that would like to make use of the raw request body.
|
||||
@ -99,7 +99,7 @@ in your room to prevent users from tampering with the script.
|
||||
This bridge supports creating small JavaScript snippets to translate an incoming webhook payload into a message for the room, giving
|
||||
you a very powerful ability to generate messages based on whatever input is coming in.
|
||||
|
||||
The input is parsed and exectuted within a seperate JavaScript Virtual Machine context, and is limited to an execution time of 2 seconds.
|
||||
The input is parsed and executed within a separate JavaScript Virtual Machine context, and is limited to an execution time of 2 seconds.
|
||||
With that said, the feature is disabled by default and `allowJsTransformationFunctions` must be enabled in the config.
|
||||
|
||||
The code snippets can be edited by editing the Matrix state event corresponding to this connection (with a state type of `uk.half-shot.matrix-hookshot.generic.hook`).
|
||||
@ -114,7 +114,7 @@ Transformation scripts have a versioned API. You can check the version of the AP
|
||||
at runtime by checking the `HookshotApiVersion` variable. If the variable is undefined, it should be considered `v1`.
|
||||
|
||||
The execution environment will contain a `data` variable, which will be the body of the incoming request (JSON will be parsed into an `Object`).
|
||||
Scripts are executed syncronously and expect the `result` variable to be set.
|
||||
Scripts are executed synchronously and expect the `result` variable to be set.
|
||||
|
||||
If the script contains errors or is otherwise unable to work, the bridge will send an error to the room. You can check the logs of the bridge
|
||||
for a more precise error.
|
||||
@ -152,7 +152,7 @@ if (data.counter === undefined) {
|
||||
### V1 API
|
||||
|
||||
The v1 API expects `result` to be a string. The string will be automatically interpreted as Markdown and transformed into HTML. All webhook messages
|
||||
will be prefix'd with `Received webhook:`. If `result` is falsey (undefined, false or null) then the message will be `No content`.
|
||||
will be prefixed with `Received webhook:`. If `result` is falsey (undefined, false or null) then the message will be `No content`.
|
||||
|
||||
#### Example script
|
||||
|
||||
|
@ -55,4 +55,4 @@ have the endpoints required accessible from the internet. Authentication is requ
|
||||
- Say `jira login` to get the URL to authenticate via.
|
||||
- Click the URL sent by the bot.
|
||||
- Follow the steps, ensuring you authenticate with the right user.
|
||||
- If all goes well, you will now be connected. You can check the status and authorisatied instances by saying `jira whoami`
|
||||
- If all goes well, you will now be connected. You can check the status of authenticated instances by saying `jira whoami`
|
||||
|
@ -16,7 +16,7 @@ type of integration (e.g. GitHub repo, Jira Project) and any additional configur
|
||||
Hookshot supports several connection types, which are defined under the Room Configuration
|
||||
heading.
|
||||
|
||||
The availablilty of connection types depends on the configuration provided to hookshot.
|
||||
The availability of connection types depends on the configuration provided to hookshot.
|
||||
|
||||
|
||||
### The `!hookshot` command
|
||||
|
@ -3,7 +3,7 @@ Provisioning API for matrix-hookshot
|
||||
|
||||
# Overview
|
||||
|
||||
This document describes how to integrate with `matrix-hookshot`'s provisoning API.
|
||||
This document describes how to integrate with `matrix-hookshot`'s provisioning API.
|
||||
|
||||
Requests made to the bridge must be against the API listener defined in the config under `provisioning`, not
|
||||
the appservice or webhook listeners.
|
||||
@ -22,7 +22,7 @@ APIs are versioned independently so two endpoints on the latest version may not
|
||||
|
||||
## GET /v1/health
|
||||
|
||||
Request the status of the provisoning API.
|
||||
Request the status of the provisioning API.
|
||||
|
||||
### Response
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user