A webhook is an HTTP request triggered by an event in a source system and sent to a destination system, often accompanied by a data payload. Webhooks are automated, meaning they are automatically sent out when their corresponding event occurs in the source system.

This provides a way for one system (the source) to "speak" (HTTP request) to another system (the destination) when an event occurs and share information (request payload) about the event that occurred.

The Functioning of Webhooks

Process of Webhook Requests

Webhooks are widely used in SaaS platforms because they can support various event types based on the activities occurring within them.

To successfully receive webhook requests, you need to subscribe to one or more events (also known as topics) for which the platform provides a webhook. Whenever a webhook request is initiated, it is dispatched to your application's specified destination endpoint. This is achieved by registering your URL as the Webhook URL for the specific event.

Registering a Webhook.

Step 1: Navigate to the 'Webhooks' settings

Log in to the LIS and navigate to 'Admin Tools' on the left-hand menu. Then, select 'Lab Setup'.

Scroll down on the page and click the link for 'Add webhooks here’:

Step 2: Add Your Webhook

Here, on the 'Webhook List' page, you'll find the section for the added webhook. Click on '+ Webhook' to get started.

Fill out the form with the webhook information and then hit 'Save Webhook':

• Receiver's Name – identifier name for destination. This is a required field.

  • For this example, we will use “Demo - Report Ready.”

• Webhook Callback URL – URL that the LIS will send the POST request. This is a required field.

  • For this example, we will use a dummy public URL

• Webhook Callback Auth – the value that will be sent as an "Authorization" header during the POST request. This is for securing the webhook calls on your end and identifying the request from LIS. This is an optional field.

  • This example will demonstrate token authentication. We will check both scenarios when this parameter is defined and not specified.

• Webhook Type – the list of events to be subscribed: ORDER_REPORT, ORDER_CREATE, ORDER_REJECT, ORDER_ARCHIVE, ORDER_DATAIN, ORDER_RECEIVE, ORDER_BILLING, SENDOUT. This is a required field.

  • For this example, we will use the ORDER_REPORT event. Whenever an order is reported, LIS will inform the webhook URL.

• Send webhook to all accounts – this option defines whether webhook will be informed for all Accounts or only selected Accounts.

  • For this example, we will use a webhook for all accounts.

• Notes – additional description for webhooks.

Step 3: Consuming a Webhook

Now that you have registered for webhook requests, you must be prepared to receive them.

• LIS Webhooks are regular HTTP POST requests and should be handled as such.

• LIS Webhooks payloads are in serialized form-encoded JSON

• Webhooks are a one-way communication system; however, it is best practice to return a 200 or 302 status code to inform the source application that you have received the webhook.

Example #1:

This example shows the scenario when the Webhook Callback Auth field is defined:

• Request Headers:

• Request Payload:

Troubleshooting & Support

If you run into any issues, check the scenarios below:

Issue: Webhook Not Triggering

• Problem: Sometimes, the webhook does not trigger as expected.

• Solution:

  • Ensure that the webhook URL is correctly configured in the LIS.

  • Verify that the events you subscribed to are occurring.

  • Check for any network issues preventing the webhook from reaching your endpoint.

Issue: Webhook Timeout

• Problem: The webhook request times out before reaching your endpoint.

• Solution:

  • Check for any latency issues on your server.

  • Ensure your endpoint is capable of handling the request load.

  • Please note that the timeout threshold for the LIS is set to 30 seconds.

Issue: Security Concerns

• Problem: Security concerns regarding the data transmitted via webhooks.

• Solution:

  • Implement HTTPS for your webhook endpoint to ensure data encryption.

  • Validate each webhook request to ensure it originates from a trusted source.

  • Keep an audit log of incoming webhook requests for monitoring purposes.

Issue: Webhook Fails to Authenticate

• Problem: The webhook fails to authenticate with your endpoint.

• Solution:

  • Ensure that the authentication credentials provided in the webhook setup are correct.

  • Verify that your endpoint is configured to accept and authenticate the incoming webhook requests.

If you run into any other issues, we're here to help you every step of the way!