Webhooks and Idempotency for Deepfake Detection APIs

Why webhooks and idempotency matter for deepfake detection

A deepfake detection result usually triggers something with consequences: an account opens, a payout is released, a claim goes to an investigator. If the same result is applied twice, or an old result overwrites a new one, the damage is real. Two approvals for one applicant, a case reopened after closure, or a second charge for one file are typical failures, and all come from the same root cause: networks retry, and senders cannot know whether a message arrived.

Two separate problems hide under this heading. Webhook reliability is about receiving results safely when a service pushes them to you. Request idempotency is about sending media safely when your own call fails halfway. They need different controls, and confusing them is a common source of bugs.

How to receive deepfake detection webhooks safely

Follow a strict order: authenticate, persist, acknowledge, process. Verify the signature using the exact raw body the sender signed, before parsing it, and reject stale timestamps to block replays. The Standard Webhooks project, an open specification for webhook senders, names spoofing and replay as threats every implementation must handle, and its scheme pairs each message with an ID, a timestamp and a signature.

Once the event is verified, write its ID, type, subject and payload hash to durable storage, then return a 2xx response. Do the real work, such as updating the onboarding case, from an internal queue. A handler that calls three downstream systems before responding will time out under load, the sender will retry, and you will receive the same event again while the first copy is still running.

• Enforce a body size limit and reject unsigned or badly signed requests.
• Keep the raw body for signature checks; re-serialised JSON will not match.
• Reject events outside the timestamp tolerance the sender documents.
• Rotate signing secrets through an approved process and support two active secrets during rotation.

Deduplicating events and preventing state regression

Put a unique constraint on the event ID so a redelivery cannot create a second work item. That handles exact duplicates. It does not handle two different events that describe the same outcome, so make the business action idempotent as well: approving an applicant who is already approved should be a no-op, not a second approval.

Events also arrive out of order. A 'completed' event can land before 'processing', and a retried old event can arrive hours later. Give each case a transition table that only moves forward, for example received, analysing, scored, decided, closed, and reject any event that would move it backwards. Where the sender provides a sequence number or resource version, use it to decide which event is newer.

Retrying detection requests when the API is not idempotent

RFC 9110 defines idempotent methods as those where repeating a request has the same effect as sending it once; POST, the method most detection APIs use for uploads, is not one of them. Some APIs accept an Idempotency-Key header so a retried POST returns the original outcome. The IETF draft that tried to standardise that header reached version 07 in October 2025 and has since expired, so support varies by vendor.

Neural Defend's documentation is explicit for NeuroVerify: requests are not idempotent, each attempt can receive a new transaction identifier, and a duplicate can create another billable transaction. Its official Python and TypeScript SDKs retry only selected 429, 500 and 503 responses and deliberately skip timeouts and network failures, because those uploads may already have succeeded.

Build your own guard around that. Create a submission record keyed by your case ID and a hash of the media before calling the API. On a timeout, mark the record unknown rather than failed, and decide by policy whether to resubmit, wait for reconciliation or send the case to review. Never wrap the SDK in a second automatic retry loop.

Reconciling gaps and testing every delivery boundary

Webhooks are a fast path, not a guarantee. Run a scheduled job that finds cases stuck in a non-terminal state past their deadline and checks them against the source of truth, whether that is the vendor API or your own job store. Without reconciliation, one dropped event leaves an applicant waiting indefinitely.

Test failure, not just success. Simulate invalid signatures, stale timestamps, duplicate and reordered events, a missing event, a slow consumer, a database outage during persistence, and a crash just before and just after acknowledgement. For requests, simulate a timeout after the server accepted the upload and confirm that your code does not create a second transaction or a second decision.

What webhook and idempotency controls cannot fix

These controls make delivery correct. They do not make a result more accurate, and they cannot tell you whether a score is right. A medium-risk result delivered exactly once is still inconclusive and still needs a review owner. Signature verification proves the message came from the holder of the signing key; it says nothing about the media itself.

Webhook payloads may also carry personal data such as transaction identifiers or filenames. Keep payloads minimal, store them under the same retention rules as the rest of the case, and avoid logging raw bodies.

Building reliable integrations with Neural Defend

NeuroVerify's public contract is a synchronous request and response, so most teams receive results in the HTTP response and publish their own internal events from there; your event bus then carries the webhook concerns above. Each response includes a unique_trx_id, an outcome status of success, rejected or error, and risk fields, which give you a natural key for deduplication and audit. One request runs six signals and returns one risk score with evidence, and Neural Defend reports under 200 ms p95 on eligible image requests under defined test conditions, which keeps most selfie checks inline and reduces the number of asynchronous paths you have to make reliable in the first place. For investigation cases, NeuroDetect keeps model and version context with each analysis, so a reconciled result can still be explained later.