There are a couple new plugin hooks that were introduced in PieFed 1.6.20 that I wanted to make a post about to help spread the knowledge. As part of this, the plugins doc page has also been updated, but feel free to ask questions here as well if any come to mind.

New Community Hooks

The first two I wanted to mention are the easy ones. They are related to new communities:

1. new_local_community
2. new_remote_community

These hooks fire whenever a new local community is created, or a new remote community has been federated to your instance. The Community object is passed to the plugin directly.

A potential use-case for a plugin utilizing these hooks would be some kind of integration with a community discovery service. I already made an untested proof of concept to announce new local communities to the Threadirator service that tries to auto-federate new communities across instances for discoverability.

The Webhook Hook

Broadly speaking, this hook lets you send webhooks to your PieFed instance and process that data with your plugins. As part of this, we added a new route to PieFed, POST /webhook, that fires the webhook plugin hook whenever it handles a valid request. So, here is what happens:

1. Some other service or API or whatever, sends a POST to /webhook with some kind of json payload.
2. As long as there is a valid json payload, then the webhook plugin hook will fire and that payload will be passed on to the plugin as a dict.
3. Every plugin utilizing this hook is called sequentially, so plugins utilizing this hook, should return the original, unaltered payload in case other plugins also need to utilize it, or if the payload was intended for a different plugin.
4. After firing the webhook plugin, the PieFed instance will return a 202 to the original request to /webhook to indicate that the request was properly passed to the plugin(s) on the server.

There are some important notes I wanted to add about this plugin hook. As I already mentioned, because of the flexibility of this hook, it is quite possible that multiple plugins could be present on the same instance all utilizing it. So, any plugin utilizing this hook should do a couple things:

1. return the webhook payload unaltered for the next plugin to inspect
2. handle any input verification and authorization within the plugin
3. gracefully handle cases where the payload is not structured for, or intended for use with your plugin - just ignore it or log it instead of raising an exception

Also of note is that there is a rate limit on the /webhook route of no more than 60 requests per minute. So, if you are trying to integrate some service that is sending more requests than that, then you should look into batching them in some way or modifying the view function for your instance to remove the rate limit.

In addition to the previously existing functionality of sending email(s) when an application is ready to review, now you can also (or alternatively) send a webhook. From the readme:

This feature lets you specify a webhook url and payload that is fired when an application is ready for review. The payload is a dict that is defined in the config file. You can use variable substitution in specified fields of your payload to help support properly formatting things like message bodies. The full list of variable substitutions is documented in the config file.

It might not be desirable to do this substitution for all fields of the payload, so only fields that you specify will be formatted in this way. Add any fields you want to do variable substitution for to the webhook_format_fields list in the config file.

Upgrade notes

You probably want to rework your email templates if you previously set them up. Some variable names changed in the new email templates to make it easier to share variables across both the email and webhook functionality.

This is the beginning of a plugin that performs actions when a new user application is ready for admin review. Currently, the only feature is that it can send an email address with the registration information to a list of specified email addresses. In the future, there isn't any reason this couldn't trigger other things (webhooks, other scripts, etc.) depending on demand.