This document outlines a product requirement document (PRD) for implementing webhooks in Agency Handy, your Software-as-a-Service (SaaS) platform for project management and communication. Webhooks will enable real-time notifications to be sent to external applications when specific events occur within Agency Handy.
User Story
As an agency owner, I want to be notified in my CRM whenever a new order is created in Agency Handy, allowing for faster client onboarding. As a developer, I want to leverage webhooks to integrate Agency Handy with our custom client portal, keeping project information synchronized in real-time. select content type (JSON) Select the webhook events Identify key events within Agency Handy that trigger webhooks. Service : Creation, Update, Deletion Order: Creation, Update, Deletion. Task: Creation, Assigned, Completion, Update. Client/User: New client added/created Deletion. Proposal: Sent, Received, Accepted, Rejected Ticket: Created, Assigned to, Status Change Payment: Received, Failed Users (agency owners, admins) should be able to configure webhooks within Agency Handy. Options include: Selecting the event(s) that trigger the webhook in Agency Handy Specifying the URL of the external application's webhook endpoint. Generate an API key and a base URL Defining the data format for the webhook payload (e.g., JSON). webhook can be set active/inactive once a webhook is created a signing secret will be created Setting up authentication for secure communication (if necessary and user will select) Basic (it will require Username and password) The developer of the destination application submits their username and password to the webhook provider (Agency Handy). The provider first sends a request with no Authorization header. This request is rejected with a 401 status code by the destination endpoint which then sends back an authentication challenge using the WWW-Authenticate header. The producer then combines the username and password with a colon (:) and sends a base64 encoded version of the string in the Authorization header of the request to authenticate the request using the format: The destination endpoint receives the authenticated requests, verifies the credentials, and if valid, allows the webhook. If the credentials are not valid, the webhook is rejected. This is an verification protocol that allows users to verify their identity on a web application, receive an access token and verify each request to the web app with the access token. The authenticated request uses the Authorization header to send the token using the format below: Webhook consumers can use this strategy to authenticate webhook requests arriving at the webhook URL.
Webhook Delivery and Security: The system should securely deliver webhook notifications to configured endpoints. Implement mechanisms for error handling and retries during delivery attempts. Exponential Backoff: If your initial attempt to send a webhook fails, you don't want to keep hammering the server incessantly. Instead, you wait for a brief moment and then try again. If it fails the second time, you wait a bit longer, and the cycle continues. Jitter: Jitter is basically a fancy term for adding a bit of randomness to your retry intervals to spread out the load. It prevents all of those webhooks from hammering the server at the same moment. Dead Letter Queue: There comes a time when you have to accept that a webhook is just not getting through. After a certain number of retry attempts, it's probably best to move the event to a Dead Letter Queue. This queue stores the events that couldn't be delivered, so you can inspect them later. Perhaps there was an issue with the payload, or the receiving server's been down for a prolonged period. Our implementation: We will use an exponential backoff algorithm with jitter to prevent overwhelming servers and to avoid the thundering herd problem. If, after multiple attempts (15), we're unable to deliver a webhook, we move it to our Dead Letter Queue, providing you with the opportunity to inspect and troubleshoot the issue. Support authentication methods to ensure data security during communication. our retry system will retry exponentially. first retry will work after 1 mins then increase exponentially [1,2,4,8,16,32,64,128,256,512,1024,2048,4096,8192,16384] mins Debugging and Activity Log Track all webhook events, including: Delivery Status (Success/Failure) Provide tools to help diagnose webhook delivery issues and integration problems: Payload Preview: View the payload data sent with each webhook. Test Webhook Delivery: Manually trigger a webhook event for testing purposes. Documentation and Support: Provide clear developer documentation for using webhooks, including API references and code samples. The documentation should include our security system for the webhook, our retry system and details on how to connect the webhook. Offer technical support for troubleshooting webhook setup and integration issues. Discover Webhooks: The developer discovers Agency Handy offers webhooks through documentation or in-app messaging. Review Documentation: They access the comprehensive API reference documentation and specifically focus on the webhook section. Identify Events: The developer reviews the list of available webhook events (e.g., service creation, order update) and selects the events most relevant to their integration needs. They navigate to the Agency Handy web interface and access the webhook configuration section. They choose the desired events and enter the URL of their application's webhook endpoint. If authentication is required, they select the appropriate method (Basic or Bearer Token) and configure the credentials accordingly. (If we give multiple authentication) They can see the Payload format is JSON The developer utilizes the "Test Webhook Delivery" functionality to trigger a test event and verify their endpoint receives the notification. They can also access the webhook activity log to review past events, payload data, and delivery status for troubleshooting purposes. User Interface Considerations (UI) This section outlines considerations for designing a user-friendly interface for managing webhooks within Agency Handy:
1. Webhook Configuration:
Clear and organized layout: The interface should be well-structured, allowing users to easily find and configure webhook settings. Event selection: Present a clear list of available webhook events with descriptive labels. Consider using checkboxes or a selection list for easy event selection. Webhook URL input: Provide a clear field for entering the external application's webhook endpoint URL. Consider validation to ensure a valid URL format is entered. Authentication configuration: If authentication is available, offer separate sections for configuring Basic or Bearer Token authentication methods. Each section should clearly guide users on entering the necessary credentials. Payload format show: Show the user that the payload will be in JSON format Save and test button: Include a prominent button to save the webhook configuration and potentially another button to trigger a test webhook delivery for verification purposes. 2. Webhook Activity Log:
List view: Display a sortable and searchable table listing all past webhook events. Event details: Each entry should display relevant information, including: Event triggered (e.g., "Service Created") Payload data (truncated view with an option to expand for full details) Delivery Status (Success/Failure) Filtering options: Allow users to filter the log by event type, date range, or delivery status for easier navigation. Download functionality: Consider offering the ability to download the webhook activity log data in a CSV format for further analysis. 3. Debugging Tools:
Test webhook delivery: Provide a dedicated button or option within the configuration section to manually trigger a test webhook event for a specific event type. This helps developers verify their endpoint setup. Payload preview: When configuring a webhook, allow users to preview the example payload data associated with the chosen event type. This provides context for understanding the information sent with each webhook notification. Users can select the events that trigger webhooks within Agency Handy. The system identifies and triggers webhooks for the following events: Service: Creation, Update, Deletion Order: Creation, Update, Deletion Task: Creation, Assigned, Completion, Update Client/User: New client added/created, Deletion Proposal: Sent, Received, Accepted, Rejected Ticket: Created, Assigned to, Status Change Payment: Received, Failed Users (agency owners, admins) can configure webhooks within Agency Handy. Users can select the event(s) that trigger the webhook. Users can specify the URL of the external application's webhook endpoint. Users can generate an API key and a base URL. (recheck with dev) Users can define the data format for the webhook payload (e.g., JSON). Users can set up authentication for secure communication (auth token). webhook can be set active/inactive Webhook Delivery and Security: The system securely delivers webhook notifications to configured endpoints. Implement error handling and retry mechanisms: Exponential Backoff: Retry with increasing intervals. Jitter: Add randomness to retry intervals. Dead Letter Queue: Store undelivered events after 15 retry attempts. Support authentication methods for secure data communication. Debugging and Activity Log: Track all webhook events, including: Delivery Status (Success/Failure) Provide tools to diagnose webhook delivery issues and integration problems: Payload Preview: View the payload data sent with each webhook. Test Webhook Delivery: Manually trigger a webhook event for testing purposes. what is a test event? and what is the functionality of the test event? Test event is basically enter a test event and URL and it will send test data. What is the authentication button and what are the dropdown options? how to test it? authentication button dropdown will currently have only token. to test it please communicate with the BE team What is the number besides the event name stands for in the webhook creation? total number of event sent in that specific webhook Does this page has infinite scroll or should have pagination? search, filter, sort nothing will be there Does webhook management has filter and sort? Didn’t get any design in figma but filter and sort button is there. Does activities tab will show pending event? Does rows are clickable in activities page? What is the certain number of retry after that the webhook will be moved to dead letter queue? and if it is moved to dead letter queue will it be functional by clicking on the redeliver button? Will it redeliver the webhook or just the events of the webhook? According to the Figma the redeliver button is the event specific. Please elaborate. webhook limit:
5000, 10000, 30,000
AgencyHandy
Webhook
