August 2023 Summaries

In a secure connection using HTTPS, clients verify servers' identities by validating their TLS certificates. However, this process can fail due to incomplete certificate chains, where servers have valid certificates but lack required intermediary certificates, making it difficult for clients to establish trust. This issue affects not only webhooks but all TLS servers and web servers, leading to failed connections and other security issues. To resolve the issue, servers should return the full certificate chain in their TLS response, excluding the root certificate, and verify that the configuration is fixed using tools like Qualys SSL Test.

Svix is an enterprise-ready webhooks sending service that enables users to build a secure, reliable, and scalable webhook platform in minutes. It offers transformations, which allow customers to modify select aspects of a webhook using JavaScript, saving them from deploying redundant glue code. Transformation Templates provide pre-written transformations for popular external services like Slack, Discord, Teams, or any API, making it easier for users to connect their webhooks to these services without writing custom code. Svix's transformation templates simplify the process of sending webhooks to external services, such as Squiggle Inc., a payment processor that uses a pre-made template to send Slack messages from its webhooks, providing customers with a seamless integration experience.

This post reviews ReadMe's webhook documentation, which is part of their tool for transforming API docs into interactive hubs. The review highlights strengths in signature verification and troubleshooting, but notes areas for improvement such as clarity on the signature scheme and retry policy. The documentation also excels in testing tools, offering a feature to send test events that make developer setup easier. Overall, ReadMe's webhook implementation is specialized and effective for their specific use case, but may not be suitable for more general-purpose webhooks.

Zoom's webhook documentation is comprehensive and well-structured, providing detailed explanations of signature verification, event catalog, retry policy, troubleshooting and failure recovery, and testing tools. The documentation excels in explaining the signature scheme and providing sample code in Node.js, earning an A grade for this section. While the event catalog lists every available event type with sample payload schemas, it could benefit from a direct link to the event catalog. The retry policy is described, but with room for improvement, particularly regarding the delay between retries. Troubleshooting and failure recovery are adequately covered, but additional guidance on recovering messages that should have been sent while the endpoint was failing would be beneficial. Testing tools are available, including the ability to send test messages and generate an endpoint URL. Overall, Zoom's documentation does a great job of explaining how to set up webhook notifications, but providing tools for testing and troubleshooting would further enhance the developer experience.

Bridge can act as an HTTP server and consume webhooks from Svix with automatic signature verification, using a configuration-based approach that includes optional JavaScript transformations and forwarding to supported message queue outputs. This allows for easy setup of receivers that can process incoming webhooks, such as sending them to RabbitMQ or Redis, by defining routes and configuring input, transformation, and output settings. Bridge supports several queue backends, including GCP Pub/Sub, RabbitMQ, Redis, SQS, and a new library called Omniqueue, which aims to simplify access to more queue backends in the future. By using Bridge, developers can conveniently consume Svix webhooks without having to set up their own HTTP server or handle signature verification manually.