Integration using Webhooks

Webhooks are super useful to integrate applications

❓ What are Webhooks

When we integrate an application A with a 3rd party application B the data can flow inwards as well as outwards from A to B and vice versa. Webhooks are one of the ways to implement this integration. For example, if an event happens in Platform A it can trigger a webhook call to a web endpoint of Platform B to notify the event.

Any 3rd party application registered with Deskera through App Store or created internally by the Dev team can register for Webhook.

Webhooks vs APIs

You might wonder why we don’t just use APIs and do regular polling and write the sync up logic. As mentioned at the start of the article, Webhooks are a way of integrating 2 platforms. APIs are always an alternative but there is a key difference between these two.

API Approach (pull-based)

With the API approach, the integration piece has to frequently fetch data from the system to check if any updates were made. This a pull-based approach and minimal chances of corrupting the data but multiple calls to get the data even when the data has not changed. It also introduces a delay in receiving updates from System A to System B.

Webhooks Approach (Push-based)

As explained above, Webhooks are a push-based approach. When a change happens in System A then only the update is pushed to System. This is a very efficient approach and syncs are near real-time but the data can get corrupted/ missed if any of the updates are not received in case the receiving endpoints were down because of any reason (maintenance, crash, network issues, etc).

Webhooks Registration

To create a webhook, the caller has to provide the following

1. Name
2. URL where the platform has to post
3. list of key/ value — headers (optional) to be injected in the webhook call
4. Sample payload — to test the webhook
5. Tenant Id (if null then global platform webhook)

• This should be captured from the request; not provided explicitly
• Global webhooks can be created only by Deskera admins

6. Event type or list of event types for which this should be triggered

• Create a new Order in the System
• Create a new Bill in the system
• Create a new payment record in the System (against a Bill)
• Create a new Quote in the system
• Create a new Invoice in the System
• Receive Payment against an Invoice
• Create a new Contact in the System

Whenever a webhook is registered, the application will validate/ verify the URL by posting a sample payload and check for 200 OK status.

Trigger

Whenever an event listed above is triggered in the application, the service will find the appropriate webhooks based on event type and tenant Id and post following payload

{
   "event" : "INVOICE_CREATED",
   "data" : {
      “invoiceId”: “INV-0001”,
      “contactId”: “CBD”,
      “lineitems”: {
          ...
          ...
      }
      ...
    }
}

Logging

All event triggers/ webhooks calls should be logged with data posted as well as the response along with other appropriate details.

Conclusion

Webhooks are excellent to integrate supported platforms with other 3rd party services as well as other internal services because it helps with instantaneous and seamless transfer of information.

You may start implementing webhooks with REST endpoints, but in the future, consider the options to introduce hooks integration with external Kafka endpoints, Redis endpoints, etc as well.

This is the approach we have taken at Deskera.