Overview
======
If you have some external system (like a bug tracker) and you want to publish events into it (like update things when revisions close):
- **DO NOT** use Herald.
- Use `feed.http-hooks` in most cases.
- Subclass `DoorkeeperFeedWorker` if you need more power.
- If your external system is something like a chatroom, polling `feed.query` using Conduit (while gross) is also reasonable.
Do Not Use Herald For This!
====
Herald has architectural tradeoffs which make it very bad for publishing information into a remote system. In particular:
- Herald actions often run in-process during other workflows, and will block users. Making service calls from Herald will slow down Phabricator for everyone.
- There is no way to handle failure or retry. Making service calls from Herald will be flaky and unreliable, and there will be no way to fix these problems.
Instead, use one of the other methods.
Use `feed.http-hooks` In Most Cases
====
You can configure `feed.http-hooks` to make HTTP requests to some external server when events occur. This is the simplest and most general-purpose way to publish events: have the remote server accept the request, publish to the external system, and then return an HTTP 200.
This won't block (it happens in the daemons), and has a sane error handling / recovery / retry strategy.
The information available in `feed.http-hooks` is somewhat limited. If you need more information, file a feature request.
Subclass DoorkeeperFeedWorker
====
The "real" way the upstream does this (in Asana and JIRA) is through Doorkeeper. Doorkeeper is a large, complex system for interfacing with external tools and representing their objects locally. This is the most powerful approach, and the one you should pursue if you want your integration in the upstream, but probably overkill for most use cases.
This won't block (it happens in the daemons) and has sane error behavior. It gives you more power to process events than `feed.http-hooks` does, and can let you use user credentials to interact with remote systems.
There's no documentation on this. You can look at the Asana and JIRA publishers if you want to go down this route. This is recommended only if you have significant experience with Phabricator.
Poll `feed.query`
======
You can make a Conduit call to `feed.query` every few seconds. This isn't great, but may be a reasonable solution to some problems. You can look at `PhabricatorBotFeedNotificationHandler` for an example of this.