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 to12 tries. Between each try there is an exponential time of delay (2, 4, ..., 4096 seconds).

Security

Our webhook servers are supporting HTTPS connections to your endpoints. This secure connection ensures that no-one can have access to data we send you. In order to activate this secured mode, all you have to do is provide an "https" endpoint address when you are submitting your file for a scan.

Since your endpoint is public, everyone can send it messages if they will know the address. In order to avoid unauthorized access to the endpoint, Copyleaks uses SSL client certificate. With this client certificate you can verify the clients who use your endpoint and ensure it is actually Copyleaks. You can also use a self-signed certificate.

To get our live SSL client certificate thumbprint, make this REST API call:

GET https://api.copyleaks.com/v1/security/certificate/thumbprint

The current Copyleaks SSL client certificate thumbprint is:

8DB377C217540936E2BB81D7282AFA16BAC61A49

In order to activate this authentication method, you have to provide "https" endpoint, which supports SSL. Non-secured (http) connection does not support this feature.