Webhooks

The Copyleaks system architecture was built to support the asynchronous model. The asynchronous model allows you to get notified immediately when your scan status changes, without having to call any other methods.

System Events

Copyleaks system is able to notify you about a few different event types related to your scan. These events are critical for the scan success.

In order to allow us to fire your webhook, you will need to provide us with a valid HTTP(s) endpoint. Most of the client endpoints appear similar to this:

https://yoursite.com/copyleaks/{status}/SCAN_ID

You can see that the endpoint contains two dynamic parts:

1. {status} – This unique token will be replaced by the Copyleaks server with the right event that just took place. The optional values are:

   • completed – The scan completed successfully.
   • error – The scan ended with error.
   • creditsChecked – Copyleaks inspected the submitted file and provides you with a cost for the scan.

   Your server side should be ready to respond to these endpoints:

   https://yoursite.com/copyleaks/completed/SCAN_ID
   https://yoursite.com/copyleaks/error/SCAN_ID
   https://yoursite.com/copyleaks/creditsChecked/SCAN_ID
   	

2. SCAN_ID – While submitting a new file for a scan, you should provide a valid Scan-Id. This dynamic segment should be replaced with your actual process ID. So, if you plan to submit a new scan with the id "hello123", then you should replace this segment with this string:

   https://yoursite.com/copyleaks/{status}/hello123

   The reason behind this step is to allow you to recognize the reported scan when it returns back to you via the webhook. We do not require you to use this, however we strongly recommend to do so.

New-Result Webhook

Besides the "{status}" webhooks, there is another webhook that gradually reports newly found results, as soon as they are identified. You should use this webhook if your application is time-sensitive. This will provide you with a live stream of results and you will not need to wait for the scan to complete.

Use this webhook by filling the properties.webhooks.newResult field on the submit method (url, file or OCR).

More information provided here - newResult webhook .

Client Requirements

There are a few system requirements in order for you to use our asynchronous model. The most important one is that you should be able to receive a webhook call from our servers. This means you should have a web-server that is connected to the internet.

While we are firing a call to your server, we expect you to answer within 70 seconds. The way you should accept this call is by returning an HTTP success code (2xx). Once we have received the success code from you, we won't fire this webhook again for the same scan.

Retry Policy

As you know, the internet is an unstable environment and communication between servers (our servers and yours) is dependent on many components (routers, load balancers and more). In this unstable environment, sending messages can fail from time to time. Also, your server can be offline for a short period of time (for example, under maintenance). For these reasons, we implemented a retry mechanism to ensure your server will get the message as soon as it will be possible.

This retry mechanism takes place immediately after your server has not replied to our webhook call. The same thing will happen if your server reports internal-error (5xx codes). In these cases, we will try to fire this webhook repeatedly, until you will reply to us with a success code (2xx).

We limit the retry mechanism to 17 tries. Between each try there is an exponential time of delay (1, 2, 4, ..., 65535 seconds).

If for any reason you would like to resend a webhook for a specific scanId , you can do it using the resend endpoint ( Resend Webhook ).

At-Least-Once Delivery

In order to provide a stable environment for your applications, Copyleaks must ensure that the webhooks will reach their destination. The webhook's reliability can be affected by multiple factors. The most significant for them is network stability. As you know, a network can be unstable from time to time.

To provide reliable webhooks, we guarantee the delivery by the "At least once" strategy. This means that you will get the requested webhook at least once, but it's not guaranteed that it will be exactly once.

Although we are doing our best to deliver each webhook exactly one time (depends on retry policy), in some cases we'll provide the same webhook more than once. Your infrastructure has to be prepared for this scenario and be able to handle it.

Other resources:

npm

• Webhooks Security - Security aspects when protecting your endpoints from unauthorized access.