Webhooks Listener Documentation
Problem statement
We need to create a listener that can receive webhook notifications from AccuLynx.
Goals
- Define what a webhook is.
- Explain the benefits of using webhooks to improve our system.
- Provide guidelines for developers to implement webhooks within our system.
Non-goals
- Offer a comprehensive list of potential use cases for webhooks.
- Delve into the technical details of how webhooks operate.
What is a webhook?
A webhook is a method to automate the exchange of information between web services in real-time. It allows applications to receive data immediately upon the occurrence of an event, as opposed to having to request it periodically. When an event occurs, the webhook sends a notification to a defined URL via an HTTP POST request, which typically includes details about the event.
Benefits of Webhooks
Webhooks enhance efficiency, minimize manual data entry, and help keep data synchronized across different systems. They are commonly used in applications like chatbots, CRM systems, and payment gateways.
How to Use Webhooks
To implement webhooks, developers must:
- Register the URL that will handle the notifications.
- Define the specific events for which notifications are desired.
- Specify the format of the data to be received.
Security Considerations
Implementing webhooks requires careful attention to security to prevent vulnerabilities. Best practices should be followed to secure the connection between systems.
Example
A practical example of a webhook in action could be when a new customer registers for a service. In this case, the webhook could send a notification to the CRM system, automatically adding the customer’s information without manual entry.
Proposed solution
To facilitate third-party applications in receiving real-time updates, our system will send a notification via an HTTP POST request with JSON data whenever a specific event occurs, such as a milestone change in a job.
Guidelines for Developers
Developers can implement webhooks by:
- Creating a webhook endpoint on their server to receive notifications.
- Parsing the JSON payload to take necessary actions.
The following guidelines will apply:
- Register the webhook endpoint with our system, which will create a subscription in AccuLynx and return a secret for validation.
- Specify the events for which notifications are required.
- Define the expected JSON payload format.
Risks
- Improper Handling: Third-party applications may fail to correctly handle webhook notifications, leading to errors or data loss.
- Security Vulnerabilities: If not properly implemented, webhooks may introduce security risks.
Implementation and rollout plan
We will provide documentation and examples to assist developers in implementing webhooks effectively. Additionally, we will offer a test mechanism for developers to validate their webhook implementation prior to deployment.
AccuLynx Webhooks Schema
Notifications sent by AccuLynx will adhere to the following schema:
Field | Description |
---|---|
Type | The type of event that is receiving. It will match one if the topics selected when creating the subscription |
EventDateTime | The date and time in UTC when the event happened |
EventId | The GUID of the event |
SubscriptionId | The GUID of the subscription created within AccuLynx system |
Event | The actual data of the event. This will change depending of the type of the event being received. |
{
"topicNamee": "job-milestone-changed",
"eventDateTime": "2023-07-11T22:38:57.1993216Z",
"eventId": "a653de1a-84a6-488c-90bc-f6c8e990bf51",
"subscriptionId": "f30009c1-b6e3-432a-9a0e-6932c9fabdd8",
"Event": {
"jobId": "24732e2b-bc9f-4a7a-a0a3-6200902a6fb4",
"companyId": "f218fc64-352c-410d-86b7-36787b88b26e",
"milestoneId": 3,
"milestoneName": "Approved",
"companyUserId": "e38c052d-38ef-4bb7-90d3-9868bb623aed",
"adminId": "d133c31c-78b9-495f-a370-aa2ac43c3545",
"message": "This job was approved",
"actionLocation": null,
"milestoneDate": "2023-07-11T22:38:57.0539859Z"
}
}
Events
Milestone Changed Event
This event is triggered when a job progresses from one milestone to another.
Field | Description |
---|---|
JobId | The GUID of the Job that was updated in its progress. |
CompanyId | The GUID of the Company that owns the jobs that is the source of the event. |
MilestoneId | The Id of the new milestone for the given job. |
MilestoneName | The Id of the new milestone for the given job. |
CompanyUserId | The user that made the update in the job progress. |
AdminId | |
Message | The message entered by the user when the job progress was changed. |
ActionLocation | |
MilestoneDate | The date and time in UTC when the job progress was changed. |
{
"jobId": "24732e2b-bc9f-4a7a-a0a3-6200902a6fb4",
"companyId": "f218fc64-352c-410d-86b7-36787b88b26e",
"milestoneId": 3,
"milestoneName": "Approved",
"companyUserId": "e38c052d-38ef-4bb7-90d3-9868bb623aed",
"adminId": "d133c31c-78b9-495f-a370-aa2ac43c3545",
"message": "This job was approved",
"actionLocation": null,
"milestoneDate": "2023-07-11T22:38:57.0539859Z"
}
Success Criteria
- Developers successfully register and receive webhook notifications.
- Third-party applications effectively handle the notifications without errors or data loss.
- Security vulnerabilities and other issues are promptly identified and resolved.
Conclusion
Webhooks are a potent mechanism for automating data exchange between web services, facilitating real-time communication, and improving efficiency. Developers must ensure that they implement and secure webhooks properly to mitigate potential risks and vulnerabilities.
Updated about 1 month ago