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:
The endpoint contains two dynamic parts:
  1. {STATUS} - This token is replaced by the Copyleaks server with the relevant event, in lowercase. 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 the Shared Data Hub or a Private Cloud Hub.
  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

​
New-Result Webhook

In addition to the status webhook, 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, Copyleaks stops retrying that webhook.

​
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 any status other than 2xx, the webhook is retried, for up to 17 attempts in total (the first call plus 16 retries), following an exponential backoff strategy: 1, 2, 4, 8, 16, …, up to 32,768 seconds between attempts, about 18 hours in total. 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. 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 Shared Data Hub or a Private Cloud Hub.

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.