Clarify webhook and integration documentation

Coming from #8522:

So, in our docs we have a webhooks page…

Seeking some feedback on the terminology here. We could:

• Rename /webhooks.html to /integrations.html
• Replace Incoming Webhooks and Automation by Integrations and Automation,
• And use the term “integration” rather than “webhook” throughout the page, unless it refers to a UI option.

This would be more consistent with the UI. However, each of these individual integrations is still called “incoming webhook”:

Therefore, for full consistency, probably we should rename “incoming webhook” to just “integration”. I just checked that this is what GitHub and MailerLite do.

What do folks think?

And then, after renaming /webhooks.html, would it be wise to repurpose the URL for outgoing webhooks? Otherwise, we would keep them at https://docs.readthedocs.io/en/stable/build-notifications.html#using-webhook, including the upcoming new features introduced at https://github.com/readthedocs/readthedocs.org/pull/8522.

cc @readthedocs/advocacy @readthedocs/backend

[ericholscher]

Agreed here. I tried to figure out our GH webhook docs the other day and they’re super confusing. Definitely lots of room for improvement here, outside of renaming.

[astrojuanlu]

I get what you say, but the advantages of renaming it to “integrations” are:

• It is forward compatible with non-webhook integrations. We may or may not have this in the short term, but doesn’t harm getting used to it I think.
• We avoid confusion with outgoing webhooks
• We are consistent with the UI menus (there’s an “integrations” link and header in the settings)
• We are consistent with other products