[Question] What about webhooks/event payloads?

[MarcosCela]

Are there any plans to include an openapi specification for event payloads described in:

https://developer.github.com/webhooks/event-payloads/

Have a nice day!

[gwestersf]

Hi @MarcosCela. You have a great eye for the product and this is something we are considering. I have nothing to share in the committed public roadmap yet, but stay tuned.

[gr2m]

There is https://github.com/octokit/webhooks, which does not have JSON Schemas for the event payloads, but at least a machine-readable format for all existing webhooks with examples for most event actions, by scraping the documentation at https://developer.github.com/webhooks/event-payloads/. Among other things, we use that to derive the TypeScript definitions for all events for https://github.com/octokit/webhooks.js

[nazwr]

Would be great to see an AsyncAPI alternative specification for any event calls so the OAS doesn't become a one-size-fits-all description

[xuorig]

Thanks @nate01776, definitely something we're looking at. We're investigating both the OpenAPI 3.1 webhooks top level property and AsyncAPI. Feel free to share more thoughts!

[nazwr]

@xuorig Sounds great! I'm not aware of any Github provided services that I could subscribe to and consume events as things stand today, but if that is something that changes in the future it would be great to have a comprehensive document like the OAS spec (which webhooks make sense to be a part of) to simplify integrating - appreciate all the work that has gone into the specification!

[tdb765]

Has there been any progress on this issue? It has been well over a year. Is adding the OpenAPI still in consideration and has it been added to your public roadmap?

[gr2m]

https://github.com/octokit/webhooks has payload schemas now and it should be pretty complete. Not part of GitHub's official OpenAPI spec but it's used in production for the Octokit SDKs today

[imwiss]

Has there been any progress on this issue? It has been well over a year. Is adding the OpenAPI still in consideration and has it been added to your public roadmap?

We expect to have event payloads added to the description in the next 3-6 months. @gr2m's suggestion is also a great approach in case the timeline doesn't work for your needs.

[WyriHaximus]

@imwiss Glad to hear it's coming somewhere this year. It's a sorely missing part of the spec at the moment

[gr2m]

@WyriHaximus did you check out https://github.com/octokit/webhooks? It really is very good. And it will most likely be used as a starting point for GitHub to officially add it to the OpenAPI spec. It's a good time to give feedback on it

[WyriHaximus]

@gr2m I did, found some minor things I'll file a PR for soon. But I was hoping for an OpenAPI spec and not a JSON schema, filed octokit/webhooks#470 for that.

[DevinRiley]

We now have webhooks in the description as of the v2.1.0 release 🎉 https://github.com/github/rest-api-description/releases/tag/v2.1.0

[gr2m]

Awesome!! Congrats and thanks for letting us know!

[WyriHaximus]

@DevinRiley This is amazing news, thank you for sharing <3!