# Webhooks Overview

> Get notified immediately when your scan status changes, without having to call any other methods.

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
<br/>
<EndpointRow method="POST" url="Completed" description="Fired on scan completion event" href="/reference/data-types/authenticity/webhooks/scan-completed" />
<EndpointRow method="POST" url="Error" description="Fired on scan ended with an error" href="/reference/data-types/authenticity/webhooks/error" />
<EndpointRow method="POST" url="Indexed" description="Fires on DB index event" href="/reference/data-types/authenticity/webhooks/indexed" />
<EndpointRow method="POST" url="Credits Checked" description="Fired when credits were checked" href="/reference/data-types/authenticity/webhooks/credits-checked" />

### Suggested Endpoint Format
The recommended format for your webhook endpoint is:
```http
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**](/reference/data-types/authenticity/webhooks/scan-completed)) - The scan completed successfully.
   - **([error](/reference/data-types/authenticity/webhooks/error))** - The scan ended with an error.
   - **([creditsChecked](/reference/data-types/authenticity/webhooks/credits-checked))** - Copyleaks inspected the submitted file and provides a cost for the scan.
   - **([indexed](/reference/data-types/authenticity/webhooks/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`  

<Tip>
Including the `SCAN_ID` in the webhook URL allows you to quickly identify and track the scan. While optional, it is highly recommended. 
</Tip>
## 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). 

<br/>
<EndpointRow method="POST" url="New Result" description="Fired as soon as we collect a new result (while scanning)" href="/reference/data-types/authenticity/results/new-result" />

## 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](/reference/actions/authenticity/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.  

<Note>
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.
</Note>
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

<CardGroup cols={2}>
  <Card title="Completed Webhook" icon="circle-check" href="/reference/data-types/authenticity/webhooks/scan-completed">Learn about the completed webhook and its contents.</Card>
  <Card title="Error Webhook" icon="triangle-exclamation" href="/reference/data-types/authenticity/webhooks/error/">Understand how to handle error webhooks and troubleshoot issues.</Card>
  <Card title="Credits Checked Webhook" icon="coins" href="/reference/data-types/authenticity/webhooks/credits-checked/">Learn about the webhook for checking credit costs before a scan.</Card>
  <Card title="Indexed Webhook" icon="database" href="/reference/data-types/authenticity/webhooks/indexed/">Understand the webhook for documents indexed in the Copyleaks database.</Card>
  <Card title="New Result Webhook" icon="bell" href="/reference/data-types/authenticity/results/new-result/">Learn about the webhook that reports newly found results as they are identified.</Card>
  <Card title="Webhooks Security" icon="plug" href="/concepts/security/webhooks/">Learn how to secure your webhook endpoints against unauthorized access.</Card>
</CardGroup>