ADR-0003: Webhooks

[textbook]

Thanks for contributing to postfacto. To speed up the process of reviewing your pull request please provide us with:

• A short explanation of the proposed change:

  Make an architectural decision around integrating Postfacto with external services.

• An explanation of the use cases your change solves

  See the ADR file on the "Files changed" tab

• Links to any other associated PRs

  Would close e.g. #20, #29 and other integration-related features.

• [x] I have reviewed the contributing guide

• [x] I have made this pull request to the master branch

• [ ] I have run all the tests using ./test.sh.

• [ ] I have added the copyright headers to each new file added

• [ ] I have given myself credit in the humans.txt file (assuming I want to)

[crswty]

This makes sense to me, I have a few questions that don't necessarily need to be answered now:

1. What data do we actually send? Do we just send a list of items to a webhook or might we need to send identifying information about the retro as well (if so how would that work with multiple installs)
2. Authentication, might we have to store information to authenticate against the consumer? If so how do we do that securely and how do we handle different authentication schemes.
   • Maybe we can go back to requesters to understand what they need
3. The ADR talks a little bit about how users are currently using the API, it would be nice to see a little more documentation on why we prefer a webhook over publishing the current API

[textbook]

@crswty good questions:

1. TBD! I think identifying the retro is a nice idea, because then you can run a single receiver for multiple teams' retros. Maybe something like { "slug": "<retro-slug", "actions": ["<action content>"] }, but we can finesse this as we better understand use cases.

2. That's an interesting one. At the simplest, maybe we don't offer any authentication options. The configured hook URL can (and maybe we should document these recommendations) include a random hash either as part of the route (my-fun-webook-abc123def456.our-domain.tld), as a query param (?token=abc123def456) or both. These wouldn't require any specific work on our end. A more complex option would be to use signatures like e.g. https://mandrill.zendesk.com/hc/en-us/articles/205583257-How-to-Authenticate-Webhook-Requests.

3. Strictly I suppose they're orthogonal; we can implement webhooks whether or not we want to also support direct API consumption. However, I suspect that the main reason it's used right now is because that's the only option - if we can provide an alternative that meets users' needs, maybe that escape hatch won't get used. If we do want to support the API, I think it should be documented, versioned and we need a better security model around it (e.g. ability to generate API keys, as requested in #186, and ideally the ability to revoke them if compromised). That seems like substantially more work, now and in the future, than this proposal.