Repository navigation
misleading webhook payload schema docs #43314
Description
Code of Conduct
- I have read and agree to the GitHub Docs project's Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/webhooks/webhook-events-and-payloads
What part(s) of the article would you like to see updated?
When receiving a push event in a GitHub app, you'll receive an object with top level installation property:
"installation":{"id":...,"node_id":...}
When receiving an installation/installation_repositories event you'll receive an object with top level installation property:
"installation":{"id":...,"client_id":...,"account":...,"repository_selection":...,"access_tokens_url":...,"repositories_url":...,"html_url":...,"app_id":...,"app_slug":...,"target_id":...,"target_type":...,"permissions":...,"events":...,"created_at":...,"updated_at":...,"single_file_name":null,"has_multiple_single_files":...,"single_file_paths":...,"suspended_by":...,"suspended_at":...}
Both are documented with the description: "Installation" and the generic type "object". The only property in common is "id" (side node, I'm surprised that "node_id" isn't common, probably an implementation thing not sending it 🤔)
I'd much appreciate it if some of the properties were given a little more description, for example the entire schema of the installation object and the circumstances/conditions where some properties might not be sent. The same can be said for the following properties in the docs:
"enterprise": object
"organization": object
"repository": object
"sender": object
Which are all generically typed as "object"
I haven't found anywhere that describes the shape of these objects and the inconsistency can make an app break without warning.
edit: I found the github api schema which is useful and in my opinion, should be linked by the docs in more places (in the webhook-events-and-payloads article for example). Alternatively, a brief note in that article should mention that one typing of Installation is not the same as another and to make no assumptions.
Additional information
No response
Activity
Sharra-writes commentedon Mar 12, 2026
@bensgilbert I'll have to look into this to find out how much bandwidth we have to tackle it.
github-actions commentedon Apr 13, 2026
A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.
bensgilbert commentedon Apr 13, 2026
not stale (hopefully)!
rnagulapalle commentedon Apr 15, 2026
i think this is real docs problem, not just wording thing
from what i can see in webhook docs, fields like installation, repository, sender, organization are documented one time as generic object, and then event pages mostly show only extra fields for that event.
problem is for webhook consumer this is bit risky. same field name does not always mean same shape in all events. if dev builds typed handler or validator from docs, it can work for one event and break in another one later.
so maybe missing part is not full duplicate schema everywhere, but at least some event-level note like:
this object is partial here
this object shape is different in this event family
do not assume same structure across all webhook payloads
i think this will help lot for people building app/webhook parsers from docs, specially typed ones
bensgilbert commentedon Apr 16, 2026
that's exactly what happened to me :)
I was creating python pydantic models for deserialization of event payloads and assumed the structure of the same field was consistent across events, resulting in my program breaking and a lot of confusion
github-actions commentedon Jul 20, 2026
A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.
bensgilbert commentedon Jul 30, 2026
not stale, @Sharra-writes any progress?
github-actions commentedon Aug 7, 2026
Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀
github-actions commentedon Sep 7, 2026
This is a gentle reminder for the Technical Content team that this issue is waiting for technical review by a subject matter expert (SME).
subatoi commentedon Sep 10, 2026
Hi @bensgilbert, I'm very sorry for the delay in replying to you here, and getting this to the right place.
You already noted https://github.com/github/rest-api-description. The right thing to do here is actually to raise an issue against that repo, if you haven't already, because the content you've noted here is pulled directly from that schema.
Unfortunately we're unable to progress this issue via this repo, and I'll need to close this, but I'll try to clarify our contributing guidelines as I think they could be clearer.