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.