Callbacks

When creating a job, you can optionally provide a callbackUrl to receive a notification when the job completes. This allows you to avoid polling the job status endpoint.

Setting Up Callbacks

To enable callbacks, include a callbackUrl field in your job creation request body:

{
  "callbackUrl": "https://your-domain.com/webhook",
  "keywords": ["machine learning", "neural networks", "deep learning"]
}

Callback URL Requirements

Protocol: Must be HTTPS (HTTP and localhost URLs are not allowed)
Format: Must be a valid URL
Example: https://api.example.com/webhooks/veritus

Callback Payload

When a job completes successfully, a POST request will be sent to your callback URL with the following JSON payload:

{
  "data": [
    {
      "abstract": "Paper abstract text or null",
      "authors": "Author1, Author2, Author3",
      "doi": "10.1234/example.doi",
      "downloadable": true,
      "engine": "ss-veritus",
      "fieldsOfStudy": ["Computer Science", "Mathematics"],
      "id": "paper_id_string",
      "impactFactor": {
        "citationCount": 150,
        "influentialCitationCount": 25,
        "referenceCount": 50
      },
      "isOpenAccess": true,
      "isPrePrint": false,
      "journalName": "Journal Name",
      "link": "https://example.com/paper",
      "pdfLink": "https://example.com/paper.pdf",
      "publicationType": "journal",
      "publishedAt": "2023-01-15",
      "score": 0.95,
      "semanticLink": "https://semanticscholar.org/paper/123",
      "title": "Paper Title",
      "titleLink": "https://example.com/paper",
      "tldr": "TLDR summary of the paper",
      "v_country": "United States",
      "v_journal_name": "Journal Name",
      "v_publisher": "Publisher Name",
      "v_quartile_ranking": "Q1",
      "year": 2023
    }
  ],
  "event": {
    "api_version": "v1",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "id": "result_id_string"
  },
  "job": {
    "id": "507f1f77bcf86cd799439011"
  }
}

Callback Payload Fields

data: Array of paper results (same structure as the results field in the job status response)
event: Event metadata:
- api_version: API version used (currently “v1”)
- createdAt: ISO 8601 timestamp when the result was created
- id: Unique result identifier
job: Job information:
- id: The job ID that was returned when creating the job

Callback Behavior

When Sent: Callbacks are only sent when a job completes successfully (status: "success")
Retries: The system automatically retries failed callback requests
No Callback on Error: If a job fails (status: "error"), no callback will be sent
HTTP Method: Callbacks are sent via POST request
Content-Type: The request body is JSON with Content-Type: application/json

Handling Callbacks

Your callback endpoint should:

Return 200 OK: Respond with a 200 status code to acknowledge receipt
Process Quickly: Keep processing time under 10 seconds to avoid timeouts
Handle Duplicates: Be idempotent - the same callback may be sent multiple times due to retries
Validate Job ID: Verify the job.id matches a job you created
Store Results: Save the results data for later retrieval

Example Callback Handler

Here’s an example of a simple callback handler:

// Express.js example
app.post("/webhook", async (req, res) => {
  try {
    const { data, event, job } = req.body;

    // Validate job ID
    const jobRecord = await findJobById(job.id);
    if (!jobRecord) {
      return res.status(404).json({ error: "Job not found" });
    }

    // Store results
    await saveJobResults(job.id, data);

    // Update job status in your system
    await updateJobStatus(job.id, "completed");

    // Return 200 to acknowledge receipt
    res.status(200).json({ received: true });
  } catch (error) {
    console.error("Error processing callback:", error);
    // Still return 200 to prevent retries for application errors
    res.status(200).json({ received: true, error: "Processing failed" });
  }
});

Testing Callbacks

To test callbacks locally, you can use services like:

ngrok - Create HTTPS tunnels to localhost
webhook.site - Temporary webhook URLs for testing
RequestBin - HTTP request inspector

Note: Localhost URLs are not accepted. You must use a publicly accessible HTTPS endpoint.

Getting started

Learn

Search API

Setting Up Callbacks

Callback URL Requirements

Callback Payload

Callback Payload Fields

Callback Behavior

Handling Callbacks

Example Callback Handler

Testing Callbacks

​Setting Up Callbacks

​Callback URL Requirements

​Callback Payload

​Callback Payload Fields

​Callback Behavior

​Handling Callbacks

​Example Callback Handler

​Testing Callbacks

Setting Up Callbacks

Callback URL Requirements

Callback Payload

Callback Payload Fields

Callback Behavior

Handling Callbacks

Example Callback Handler

Testing Callbacks