Payload documentation doesn't match actual payloads


#1

The payloads documentation is full of mismatching explanations and actual payload.
When comparing to real payloads, the example payload seems to match, but the explanations have many mismatches.

I’ll give a couple of examples:

According to the explanation:

  • Push event payload:
    The Commit field is supposed to have Sha, but doesn’t suppose to have Id, Added, Removed, and Modified.

  • Nowhere it is documented that all payload includes installation field with id subfield when fired from an installation.

I remember seeing others also, but I haven’t got the time to review the full list right now.
I think this should be fixed to prevent confusion. I know I spent days trying to understand how to get an installation id when it was right there all along.


#2

There are definitely issues with the payloads, and it’s on our list to get it all straightened out.

In the meantime, I’ve found it very useful to go to the Advanced tab for my GitHub Apps and look at the deliveries—these have the exact payload that got sent.


#3

The question is how are you going to straighten this out - fixing the docs or matching the actual payload?

Currently the Octokit implementations base on the documentation, except for the parts that people detected it doesn’t work and fixed the implementation of that library according to the actual payload. However, not everywhere. For example, I currently need to handle push event using Octokit.Net, and the Commit object doesn’t have Sha field. So I don’t know what to do - should I add an Id field to the class, or wait until the payload is fixed to match the explanation docs?


#4

I believe that we will be updating the docs to match the payloads, not the other way around.


#5

Specifically the Commit payload is different in PushEvent payload (for example) and Status payload (for example).
See https://github.com/octokit/octokit.net/issues/1789 for details.
Is this something you may change? Should I wait until the two payloads are the same or go ahead and create a new class?


#6

Ah, this is a different problem than the one you originally reported. The PushEvent is very old, and we cannot change the payload structure to match other Commit payloads, since that would be a breaking change.

I have opened an issue with the docs team to address the inconsistency in the descriptions compared to the actual payload for the PushEvent.

Nowhere it is documented that all payload includes installation field with id subfield when fired from an installation.

The event payloads are used in two contexts. They are returned from the v3 API in the Events API, as described in https://developer.github.com/v3/activity/events/types/

They are also used in the context of webhooks, which are documented here:
https://developer.github.com/webhooks/ which explains the differences between the payloads in the two contexts.

Each event type has a specific payload format with the relevant event information. All event payloads mirror the payloads for the Event types, with the exception of the original push event, which has a more detailed webhook payload.

In addition to the fields documented for each event, webhook payloads include the user who performed the event (sender) as well as the organization (organization) and/or repository (repository) which the event occurred on, and for a GitHub App’s webhook may include the installation (installation) which an event relates to. An example is given in the PullRequestEvent payload.


#7

I re-read the documentation for the PushEvent, and realized that the Note explains the discrepancy.

The table lists the keys that are present when the Push event is returned from the v3 API, and the webhook example lists sample JSON as delivered by webhooks.