List Callback Failures via the attachmentAV API

When you scan large files asynchronously with the attachmentAV Virus and Malware Scan API, you can have the result delivered straight to your application through a callback URL (webhook). It is fast, simple, and keeps your code free of polling loops—right up until the moment a callback does not arrive.

Networks hiccup, endpoints get redeployed, TLS handshakes fail, and load balancers return the occasional 503. When that happens during callback delivery, a scan result you were counting on can quietly slip through the cracks. Today, we are closing that gap with a new API endpoint that lets you list callback failures.

The Challenge: Silent Webhook Failures

Callbacks are the most convenient way to receive asynchronous scan results. You submit a file—via S3 or a download URL—together with a callback_url, and attachmentAV sends the verdict to that endpoint via an HTTPS POST as soon as the scan completes.

To make delivery robust, attachmentAV already retries a failed callback. If your endpoint does not respond with a 2xx status code, we retry at least three times with delays of 5, 10, and 15 seconds. That handles the vast majority of transient problems.

But what if every attempt fails? Maybe your endpoint was down for a deployment, a firewall rule changed, or a certificate expired at the worst possible time. Until now, that scan result was lost to you, and—worse—you had no easy way to even know it happened.

The Solution: A Failure Log You Can Query

With the latest update to the attachmentAV Virus and Malware Scan API, every callback that still fails after the final retry is recorded. You can inspect these records at any time through the new endpoint:

GET /v1/callback/failures

Each failure entry tells you exactly what could not be delivered and why:

• id — the ID of the failure.
• time — when the callback failed (YYYY-MM-DDTHH:MM:SSZ).
• download_url — the file that was scanned.
• callback_url — the endpoint we tried to reach.
• error_json — structured metadata about the error, so you can tell an ECONNRESET from an HTTP 500.

Failures are stored for 30 days and returned sorted by time in descending order, so the youngest failure comes first. This gives you a reliable audit trail and a recovery mechanism: read the failures, look up the affected files, and re-scan or re-process them as needed.

How it works

You query the endpoint for a specific callback_url. Because a busy integration can accumulate many failures, results are paginated with a cursor—pass the next_cursor from the previous response to fetch the next page.

Here is a plain curl request:

curl \
  -i \
  --retry 5 \
  --retry-all-errors \
  --fail \
  -H 'x-api-key: <API_KEY_PLACEHOLDER>' \
  'https://eu.developer.attachmentav.com/v1/callback/failures?callback_url=https://api.yourcompany.com/attachmentav/callback'

The response is JSON:

{
  "failures": [
    {
      "id": "09bf7876-68ea-2c29-8ed5-272698a70f0e",
      "time": "2026-07-09T18:31:02Z",
      "download_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      "callback_url": "https://api.yourcompany.com/attachmentav/callback",
      "error_json": "{\"message\":\"callback URL ... failed: Client network socket disconnected before secure TLS connection was established, retry\",\"code\":\"bucketav:callback-failed\",\"metadata\":{\"error\":{\"message\":\"Client network socket disconnected before secure TLS connection was established\",\"code\":\"ECONNRESET\"}}}"
    }
  ]
}

Prefer to use one of our SDKs? Here it is in JavaScript / TypeScript:

import { AttachmentAVApi, Configuration } from '@attachmentav/virus-scan-sdk-ts';

const config = new Configuration({
  apiKey: '<API_KEY_PLACEHOLDER>'
});
const api = new AttachmentAVApi(config);

const res = await api.callbackFailuresGet({
  callbackUrl: 'https://api.yourcompany.com/attachmentav/callback'
});
console.log('Callback failures', res);

We also provide examples in:

• Java
• Python
• JavaScript (mjs/cjs)

Make sure to update to SDK to get the new method.

Why This Matters

• No more silent data loss: Every undelivered scan result is captured, so an outage on your side never means a missing verdict.
• Faster recovery: Poll for failures on a schedule, re-fetch the affected files, and reconcile automatically.
• Better observability: The structured error_json makes it easy to spot systemic problems—an expired certificate, a misconfigured firewall, or a flaky downstream service.

Note: This endpoint is only available for asynchronous scans (POST /v1/scan/async/s3 or POST /v1/scan/async/download) submitted with a callback_url. Like other metadata endpoints, a request counts against your monthly quota even though it does not scan a file.

Powered by Sophos

The new callback failures endpoint is available today for our SaaS customers. As always, attachmentAV is powered by the Sophos engine and is fully ISO 27001 certified and GDPR compliant, ensuring your data remains secure and private.

Get Started

Ready to make your webhook integration bulletproof?

• Update your SDK.
• Read the documentation for more details.

Happy (and safe) coding!