Clarify webhook and integration documentation

[astrojuanlu]

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 #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.

[stsewd]

And then, after renaming /webhooks.html, would it be wise to repurpose the URL for outgoing webhooks?

We would need to create a redirect from webhooks.html to integrations.html, so, we can't re-use that page that easily (or maybe it's fine, and having a note about the old page being moved).

Also, I think the title could be just Integrations or VCS Integrations (dropping the "automation" part, as that page doesn't include anything extra).

[astrojuanlu]

We used VCS Integrations for this guide https://docs.readthedocs.io/en/stable/guides/vcs.html which might benefit from a renaming as well...?

[ericholscher]

@astrojuanlu Definitely feel free to do a larger rename/refactor here. Lots of naming debt, so make a proposal 👍

[humitos]

I'd avoid using "Integrations" unless we provide something else than a webhook. When using "webhook" is clear that we will send/receive a request with data, nothing else. On the other hand, "integration" conveys a lot more work done between the parts involved in the integration. An example of integration to me are GitHub Applications and/or Slack Applications.

[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