Inconsistency between events API and webhook payload

[jizi]

With changes announced in https://github.blog/changelog/2025-08-08-upcoming-changes-to-github-events-api-payloads/ it seems there is now inconsistency between the payload returned in the events API and in the payload of the GitHub webhooks.

In this issue #3665, the deprecation notes have been added. These are fully valid as the events API payload no longer contains these fields but as the same struct is used to unmarshal the webhook payloads it is now inconsistent because webhook payload still contains the fields deprecated on the event API.

This part of code

go-github/github/repos_hooks.go

Line 26 in 06ab3a2

type WebHookPayload = PushEvent

says that the structures are the same but in fact that's no longer true.

Are there any plans to split the implementation for events API and webhooks?

[gmlewis]

My understanding is that you wish to split WebHookPayload and PushEvent into two separate structs so that fields that are no longer populated will no longer exist in the struct, correct?

The benefits would be:

• increased clarity
• less developer confusion

Are there any other benefits?

My biggest concern is very similar to my concerns stated in #3866 (comment) - we have many users of this repo running on GitHub Enterprise which could be on any previous version of the GitHub v3 API.

Another thought I have is that we very frequently re-use structs in this repo for many purposes where fields are sometimes populated by GitHub v3 API endpoints and sometimes not by other endpoints.

I would like to hear your thoughts about this, and let's also leave this issue open for others to comment in case there are some good ideas as to how best to address this.

[jizi]

Thanks for fast reply :-)

My understanding is that you wish to split WebHookPayload and PushEvent into two separate structs so that fields that are no longer populated will no longer exist in the struct, correct?

Probably. As the payloads for events API and webhooks are not the same there is probably no other clear way to handle this. Now it is still usable and probably only the documentation of the struct could be sufficient. The worst case would be that the fields are removed here as someone could do it based on the current comment not realizing it is also used for the webhook payload.

My biggest concern is very similar to my concerns stated in #3866 (comment) - we have many users of this repo running on GitHub Enterprise which could be on any previous version of the GitHub v3 API.

I see. So maybe I am only overcautious and was afraid that you could (in near future) remove the deprecated fields which would cause issues for the developers using it to unmarshal the webhook payload.
Then maybe it would be enough to update the comment in the code that the deprecation is (currently) relevant just for events API.

[gmlewis]

Then maybe it would be enough to update the comment in the code that the deprecation is (currently) relevant just for events API.

That sounds like an excellent idea. Would you like to submit a PR that would clarify the situation, @jizi?

[jizi]

@gmlewis in the end it seems that only Commits field is still present in webhook payload. The rest of deprecated fields has been removed from both Events API and webohook payload. So Ive updated only the comment for the Commits field.
Can you please review?