Web Hooks

The term webhook is an extension of the term hook, altering the behavior of a system, first used by Jeff Lindsay in 2007. Webhooks are user defined callbacks that allow for the alteration of data or behavior of a website through a third party application. They are typically not built or maintained by the developers who are using them so they have to be able to interact with a variety of systems. Webhooks are used for a variety of functions. Most commonly they are used in continuous integrations systems to trigger builds and releases as well as in tracking systems to notify developers of bugs before they become a problem. A common website use is in payment processors so that they client does not have to worry about personally identifiable information or financial security, those are on the third party providing the webhook. When triggered the client will send an HTTP request to the webhook’s URL where the service will act on the information and call back into the client’s system with a return object. Events like submitting an order request or accepting a pull request into the main branch are typical triggers for webhooks. The URL, triggering events, and sometimes the return objects are configurable when setting up the webhook. At some point in your career you are likely to find yourself building or maintaining a webhook, if not you will definitely be consuming them. Understanding the basics as well as some of the best practices around them will help you to navigate what could otherwise be a confusing world of HTTP requests and callback logic. Use the information here to better understand how to build and work with webhooks. It is not comprehensive, but more of a starting place for you to better understand and show you where to look in order to dive deeper. Episode Breakdown User Interface For Setting-Up Webhook For each disparate event that your system emits there needs to be the ability to let it call a different webhook. It may be a different system that they want it to call into. Users need to be able to configure different environments (dev, test, uat, prod) and be able to configure them individually. Developers do not need access to production, nor should you want access as a developer. Your calls need to have an authentication mechanism such, as a key-pair, to make sure that you are who you say you are. These need to be different between environments. The user interface needs to automatically test the webhook to check that is actually working once it is set up. Testing Mechanism for Developers Developers need to be able to shape the data and send it through the process for each webhook available. Make sure to include the ability to test error conditions. That makes manual testing easier for the developer while setting up. The developer also needs to be able to see how their system responded and in what kind of time period it did so. Special characters and things like dates need to be rich input so that developers can see how the system will handle it based on what they send in via JSON. Constraints that are on the outgoing payload needs to also apply to the testing and incoming payload. Understand Return Object Shape Be specific about what is expected in the return especially with HTTP status codes so that consumers know what to expect when using the webhook. The return payload needs to be in the HTTP body, not in headers or other weird areas. Make sure this is highlighted in the testing interface if incorrect. Provide examples or sample return objects so that consumers can build for what they will receive before they begin consuming. Be lenient in the what you accept, but be specific about formatting of known types. Make sure that the return error codes are understandable and easy to find in the documentation. Allow developers to manually validate their return payload...