Determining which installation an event came from


#1

I’ve written an integration I’d like to use across multiple organizations. If an integration is installed on multiple accounts†, how can we tell which installation a given webhook event originated from?

As far as I can tell, you have to:

  1. Watch for an installation event
  2. Grab the installation ID and organization/username
  3. Persist these identifiers together and do a lookup based on the organization/user a webhook affects

This feels pretty brittle and overly complicated. For example, If you miss an installation event at any point, there doesn’t seem to be any way to retrieve a list of installation IDs after the fact; if an installation event webhook failed due to a networking error, or if the webhook consumer dropped the event or otherwise processed the event incorrectly, seems like the only way to fix the integration is to have the user uninstall and reinstall it. (Problem being, you likely won’t know who to tell to reinstall your integration!)

Seems like an easy way to solve this problem would be to include an installation_id property on the webhook payload (or a header, etc.) that corresponds to the installation from which the event originated. This would make the flow of using integrations way easier; your webhook consumer wouldn’t have to track a lot of complicated state, and missed events wouldn’t be quite so catastrophic.

Am I missing something fundamental here?

† Sidenote—I can’t figure out how to install an integration I’ve listed as public on multiple accounts, but that’s a separate issue.


#2

This would be hugely helpful. Another useful thing would be if GitHub provided a way for developers to pass information in a query string to the URL on GitHub where a user would install our integration. Then if the user actually installs the integration from that page with the query string it would pass that information along in the initial installation event. Maybe just one “state” query string parameter.


#3

I started working on migrating mention-bot to an integration, and very quickly ran into this issue. It doesn’t persist any state, so it would need to be able to get an installation from the webhook (including installation_id in the webhook as @ndhoule suggested would be great; an API to look up the installation for a repository would work).


#4

There is the possibility of paging through the whole list of installations but that doesn’t scale, and there’s no reason for stateless applications to have to implement caching on Their side…


Request support for additional endpoints for Integrations
#5

Thanks folks for the feedback on this. We’re looking into a solution to make that easier, and will update this thread when there’s more info.

There isn’t a way to install on multiple accounts, you would need to install individually on your personal account or any organization you administer.


#6

I think the issue is something else. It took me quite a while to figure out how to even install an integration anyhwere other than in the org or user account that created it. Only after you install the integration into the owning org/user does a list of other orgs appear at the very bottom of the integration configuration page that lets you install the integration into other orgs. The only way I know to install a public integration which you do not own yourself and which is not listed in the GitHub directory is by creating a deep link with the integration id, based on the URL the install button takes you to for your own organization.


#7

If that’s the case, then this UI element should probably be removed:

I haven’t actually figured out how to do what the button describes. What @naderman describes sounds like what I tried to do; seems fairly unintuitive and kinda reflects my confusion.


#8

If your Integration is made public - so available for anyone to install, not just “internal” - your settings page will include a Public link you can share. Anyone can install a public Integration from that page, for example if I visit the Codecov integration page (https://github.com/integration/codecov), I see the options to install on my personal account, or one of the organizations I can administer:

To make sure we understand the problem - is the confusion in discovering what that URL is? Or are you experiencing a problem with the flow once there?


#9

Nope, the UI is pretty unambiguous now. (Either those UI elements were there when I initially wrote this—fairly sure this is the case—or I just missed them.) Thanks!


#10

I just want to +1 having events pass along the installation id (or the installation object defined: https://developer.github.com/v3/integrations/#find-installations).

Having the event pass the installation ID will allow me to generate authentication tokens to use with other APIs. In my case, receive the PullRequestEvent and post a comment if required. Currently I need to listen for the IntegrationInstallationEvent and persist (or remove) the installation ID, storing this and the account ID to look up later. It’s fine now, but I’d rather not have the requirement to have a database (and the issues that comes with - i.e. availability).


#11

Hi folks,

We’ve added the installation id to the payloads an Integration’s webhook will receive. So you’ll now see an installation hash included in the payload, currently only including the id, something like:

{
	"action": "synchronize",
	"number": 1,
	"pull_request": {
		"url": "https://api.github.com/repos/acme/design/pulls/1",
		"id": 1984
	},
	"sender": {
		"login": "keavy",
		"id": 42
	},
	"installation": {
		"id": 9
	}
}

Payloads docs.

Hope this helps. Let us know if you have any questions.


#12