Async · Callbacks

DrillBit Webhooks
API Documentation

DrillBit processes submissions asynchronously and pushes results straight to your application. When analysis completes, a PUT request is delivered to your registered callback URL with the full report payload - no polling required.

View Payload Register Callback URL

Delivery Method

PUT

Sent to your registered endpoint

Typical Processing

10–15min

From upload to callback

Expected Response

200 OK

Your endpoint must acknowledge

Overview

Callback-based, no polling

Plagiarism and AI-content analysis run in the background after a file is uploaded. Rather than repeatedly polling for status, you register a callback URL once and DrillBit notifies you the moment results are ready.

Register your endpoint first

Webhook delivery requires a registered callback URL. Contact support@drillbitplagiarism.com to register the endpoint where DrillBit should deliver results. Your endpoint must be publicly reachable and accept a PUT request with a JSON body.

How it works

The callback workflow

Three steps, fully asynchronous - your application stays free while DrillBit does the analysis.

① Upload filevia the submission endpoint

② DrillBit processestypically 10–15 min

③ PUT callback sentto your endpoint

Callback Payload

What DrillBit sends you

When analysis is complete, DrillBit sends a PUT request to your registered callback URL with the following JSON fields.

Field	Type	Description
paper_id	integer	Unique identifier for the processed document.
similarity	string	Similarity percentage for the submission (e.g. `"23%"`).
download_url	string	URL to download the full similarity report (PDF).
flag	integer	Error flag - `1` = error during processing, `0` = no error.

// PUT request delivered to your registered callback URL
PUT https://partner-api.example.com/drillbit/callback
Content-Type: application/json

{
  "paper_id":     200101,
  "similarity":   "18%",
  "download_url": "https://s1.drillbitplagiarismcheck.com/reports/200101",
  "flag":         0
}

Your Endpoint

Expected response

Your callback endpoint must accept the payload and acknowledge receipt so DrillBit can mark the delivery as complete.

Status Code	Meaning
200 OK	Payload received - DrillBit considers delivery complete.
4XX / 5XX	Error - DrillBit treats the callback as failed.

Acknowledge promptly

Your endpoint must respond with 200 OK within a reasonable timeout. No specific response body is required - an empty 200 is sufficient. Do the heavy lifting (parsing, storage) after acknowledging.

Best Practices

Build a reliable receiver

Apply these patterns so your callback handler is resilient to retries, slow processing, and partial failures.

Respond fast, process later. Return 200 OK immediately, then queue the payload for processing. Long-running work inside the handler risks a timeout that marks delivery as failed.

Key on paper_id. Use it to correlate the callback with the original submission, and to de-duplicate in case the same result is delivered more than once.

Check the flag. A value of 1 means processing failed for that document - surface it for review rather than treating the callback as a success.

Keep the endpoint public & stable. The callback URL must stay reachable over HTTPS. If it changes, register the new URL with support before switching over.

Fetch reports via download_url. Pull the report when you need it using your authenticated API key - don't assume the link is publicly accessible without authorization.

FAQ

Frequently asked questions

How do I register my callback URL?

Contact support@drillbitplagiarism.com with the HTTPS endpoint where DrillBit should deliver results. Webhook delivery is enabled once your callback URL is registered against your account.

Why a PUT request instead of POST?

DrillBit delivers the completed result for a known paper_id by sending a PUT to your callback URL with the final report payload. Your endpoint simply needs to accept the request and return 200 OK.

How long does processing take before the callback fires?

Analysis is asynchronous and typically completes in 10–15 minutes, though it can vary with document size and queue depth. The callback is sent as soon as results are ready.

What should my endpoint return?

Respond with 200 OK to confirm receipt. Any 4XX or 5XX status is treated as a failed delivery. No specific response body is required.

What does the flag field mean?

flag indicates whether processing encountered an error: 0 means the document was processed successfully, while 1 indicates an error occurred for that submission.

Which products support webhook callbacks?

Webhook callbacks are part of both the Folder Management and Classroom Management APIs. The callback contract described here applies to both.

Continue exploring the DrillBit API

Head back to the developer portal for product references and quick-start guides.

Back to home