matrix-org / matrix-org/matrix-hookshot

Support for Outbound Webhooks

Open
#942 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Generic Hook T-Enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.