Yesterday, I spent some time on IRC with Mike figuring out this whole webhooks thing. Before that, all I knew was that webhooks are used to notify external services when something is updated. Mike explained a lot to me, so I thought I’d write about it here to help myself get it all laid out nicely.
I need to build a new extension. It must:
- Register to listen to Review Board events.
- When an event happens, turn the information into JSON or XML (I’m not sure which at this point.).
- Find the appropriate webhook.
There are some things I need to consider, such as:
- There may need to be webhooks that are distinct between repositories within one instance of ReviewBoard.
- I need to determine how information will be serialized into JSON or XML.
- The extension should be designed for testability, so we should be able to modify it so instead of sending out a POST, it prints out something we can test.
Hopefully some of these issues will already have been decided on in the original webhooks code. Anything that hasn’t been, I’ll be deciding along the way.
So in the current webhooks code, a Webhooks class is defined in models.py. It has a dispatch method, which is where the payload is turned into JSON and the POST is sent. The actual POSTing is done in another file called post_url_dispatcher.py. In admin.py, there exists functionality allowing users to change the url for each webhook through the admin interface.
One problem we came across was that in the current code, publishing reviews, review requests, etc. was generalized into publishing. Mike and Christian both said that they disagree with this generalization, so I’ll have to figure out how to separate them when I write the extension.
The rest of the code is largely signal passing stuff, which I think I understand fairly well.
So basically, this is what I need to do next:
- Create a skeleton extension in rb-extension-pack, like I did for my Excel exporter.
- Create a webhook model in the extension.
- Have the extension register for a signal.
- Make sure I can configure the extension with webhooks to associate with various things. This has something to do with GenericForeignKeys. I’m a little fuzzy on what this part means at the moment…
For now, the extension should be dealing with the following types of signals:
- The publishing of review requests, reviews, and replies.
- Discarding/deleting/submitting review requests.
- Diff updates/publishing of drafts.
Also, these are the Django docs I should read if I need to further understand some things:
As of right now, I think I’m understanding what I need to do pretty well, though questions will no doubt come up as I get deeper into the code. But overall I feel more on track now, thanks to Mike’s explanations and seemingly infinite patience.