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:

1. Register the URL that will handle the notifications.
2. Define the specific events for which notifications are desired.
3. 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:

1. Register the webhook endpoint with our system, which will create a subscription in AccuLynx and return a secret for validation.
2. Specify the events for which notifications are required.
3. 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:

{
  "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.

{
    "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.