After February 2018:

• Probably just use Webhooks.

Before February 2018:

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.

The full feed is published, regardless of view policies, see T5726#88706.

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.