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

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).

​
Webhooks


​
Suggested Endpoint Format

The recommended format for your webhook endpoint is: 
https://yoursite.com/copyleaks/{status}/SCAN_ID
The endpoint contains two dynamic parts:
  1. {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.
  2. SCAN_ID - This segment should be replaced with your actual process ID.

​
Example

If your scan ID is hello123, your webhook endpoints would be:
  • https://yoursite.com/copyleaks/completed/hello123
  • https://yoursite.com/copyleaks/error/hello123
  • https://yoursite.com/copyleaks/creditsChecked/hello123
Including the SCAN_ID in the webhook URL allows you to quickly identify and track the scan. While optional, it is highly recommended.

​
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).

​
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

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

Copyleaks follows an “at-least-once” delivery approach, ensuring that webhooks are always sent, even in cases of temporary failures.
While a webhook is guaranteed to be sent, it may be delivered more than once in rare cases. Your system should be designed to handle duplicate webhook notifications gracefully.
By implementing these best practices, you can ensure seamless integration with Copyleaks’ asynchronous webhook system while maintaining the security and reliability of your application.

​
Next Steps

Completed Webhook

Learn about the completed webhook and its contents.

Error Webhook

Understand how to handle error webhooks and troubleshoot issues.

Credits Checked Webhook

Learn about the webhook for checking credit costs before a scan.

Indexed Webhook

Understand the webhook for documents indexed in the Copyleaks database.

New Result Webhook

Learn about the webhook that reports newly found results as they are identified.

Webhooks Security

Learn how to secure your webhook endpoints against unauthorized access.