matrix-org / matrix-org/matrix-hookshot
Support for Outbound Webhooks
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 450
- Forks
- 95
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 23
Description
Some users want bi-directional hookshottin', where messages from Matrix are sent along to a remote platform. So, this is the plan.
A new connection type called "Outbound Generic Webhooks" will be setup, with a very similar structure to the incoming webhooks. The default payload will be a JSON message containing the Matrix event structure.
The request will be a simple PUT to the URL specified in the state. There will be a `X-Matrix-Hookshot-EventId` header containing the event ID, as well as a as-yet-unspecified authentication token header. The token will given once during creation and can be refreshed, and will be given on each request.
Requests will be retried in a limited sense on failure, the limits will be configurable but the defaults will be to retry up to 5 times (in increasing delays) to hit the service. With Redis mode on, there may be the possibility of batching up events to send later but this is probably not part of the V1 feature.
For media messages, the payload will include the media (hookshot will download, and if required, decrypt it) as a blob on the upload. The default solution will be to include it as part of a multi-part response, where the JSON and the media will be separate parts.
Finally, it goes without saying this is not intended to be a replacement for Appservices which is a far more powerful and effective API for building proper Matrix integrations. However, if the platform you are integrating to is extremely limited then this may be an effective starting point.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the existing incoming webhook connection implementation and tracing how connection state and requests are handled. Define the outbound generic webhook connection, its PUT payload and headers, authentication-token lifecycle, retries, and media handling from the issue; Redis batching is explicitly deferred from V1.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- redis, typescript
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100