Webhooks Overview
A webhook is an automated message sent from an application when a specific event occurs. Think of it as a push notification for your server.
Instead of your application repeatedly asking the Copyleaks API, “Is the scan finished yet?” (a process known as polling), a webhook lets our servers notify you automatically as soon as an event happens. This approach is far more efficient and provides real-time updates.
Since authenticity scans can take time to complete, webhooks are essential for building a responsive and scalable integration. By using them, you can get immediate notifications for key events—like when a scan is completed, an error occurs, or the credit cost is calculated - without writing complex polling logic.
This page explains how to configure your endpoints to receive these events and what to expect from our system.
System Events
Section titled “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.
To allow us to fire your webhook, you will need to provide us with a valid HTTP(s) endpoint. You can do this by populating the properties.webhooks.status field in the submit method (URL, file, or OCR).
Suggested Endpoint Format
Section titled “Suggested Endpoint Format”The recommended format for your webhook endpoint is:
https://yoursite.com/copyleaks/{status}/SCAN_IDThe endpoint contains two dynamic parts:
-
{status}– This token is replaced by the Copyleaks server with the relevant event. Possible values include:- (completed) – The scan completed successfully.
- (error) – The scan ended with an error.
- (creditsChecked) – Copyleaks inspected the submitted file and provides a cost for the scan.
- (indexed) – Copyleaks indexed the submitted file in its Shared Data Hub or repository.
-
SCAN_ID- This segment should be replaced with your actual process ID. For For example, if your scan ID ishello123, the endpoint would be:
Example
Section titled “Example”If your scan ID is hello123, your webhook endpoints would be:
https://yoursite.com/copyleaks/completed/hello123https://yoursite.com/copyleaks/error/hello123https://yoursite.com/copyleaks/creditsChecked/hello123
New-Result Webhook
Section titled “New-Result Webhook”In addition to the {status} webhooks, there is a new-result webhook that reports newly found results as they are identified. This is useful for time-sensitive applications, providing a live stream of results without waiting for the scan to complete.
To use this webhook, populate the properties.webhooks.newResult field in the submit method (URL, file, or OCR). For more details, refer to the (new result webhook) documentation.
Client Requirements
Section titled “Client Requirements”To use the asynchronous model, your system must meet the following requirements:
- A web server connected to the internet.
- The ability to respond to webhook calls within 70 seconds with an HTTP success code (2xx).
- Once a success code is received, the webhook will not be fired again for the same scan.
Retry Policy
Section titled “Retry Policy”To ensure reliable delivery, Copyleaks implements an automatic retry mechanism in case of communication failures (e.g., server downtime, network instability).
If your server fails to respond or returns a 5xx error, the webhook will be retried up to 17 times, following an exponential backoff strategy:
1, 2, 4, 8, 16, …, up to 65,535 seconds between attempts.
To manually resend a webhook for a specific scan, use the resend webhook endpoint.
At-Least-Once Delivery Guarantee
Section titled “At-Least-Once Delivery Guarantee”Copyleaks follows an “at-least-once” delivery approach, ensuring that webhooks are always sent, even in cases of temporary failures.
By implementing these best practices, you can ensure seamless integration with Copyleaks’ asynchronous webhook system while maintaining the security and reliability of your application.