Webhook Management

Instead of polling for analysis status changes, you can configure a webhook to receive real-time notifications.

Overview

When configured, the API automatically sends HTTP POST requests to your webhook endpoint for all analysis status transitions, eliminating the need for polling.

• Single webhook per tenant: Configure one webhook URL in your tenant settings
• Real-time status notifications: Receive updates for all status changes during analysis processing
• Simple configuration: Manage via PUT /v1/tenant endpoint
• Non-blocking delivery: Webhook calls don’t affect analysis processing

Status Change Notification Workflow

We call the webhook URL on every status change:

• create - New analysis created
• update - Analysis status changed (pending => processing => completed)
• delete - Analysis deleted

The following diagram shows when webhooks are triggered during the analysis lifecycle.

sequenceDiagram
    participant Client
    participant API
    participant Scheduler
    participant Inference
    participant Webhook as Your Webhook

    Client->>API: POST /v1/analysis (create analysis)
    API-->>Client: 200 OK (status: pending)
    
    Note over Scheduler: Analysis Scheduler Job runs
    
    Scheduler->>API: Lock analysis for processing
    Scheduler->>Webhook: POST webhook (status: processing)
    Note over Webhook: Status: processing<br/>Processing started
    
    Scheduler->>Inference: Run inference
    
    alt Inference successful
        Inference-->>Scheduler: Return results
        Scheduler->>API: Update analysis (status: completed)
        Scheduler->>Webhook: POST webhook (status: completed)
        Note over Webhook: Status: completed<br/>Results available
    else Inference failed
        Inference-->>Scheduler: Return error
        Scheduler->>API: Update analysis (status: failed)
        Scheduler->>Webhook: POST webhook (status: failed)
        Note over Webhook: Status: failed<br/>Error occurred
    else All instances busy
        Scheduler->>API: Rollback to pending
        Scheduler->>Webhook: POST webhook (status: pending)
        Note over Webhook: Status: pending<br/>Re-queued for retry
    end
    
    Client->>API: GET /v1/analysis?id=xxx
    API-->>Client: Analysis with current status

1. Client creates analysis: Initial status is pending, no webhook called
2. Scheduler locks analysis: Status changes to processing, webhook called
3. Inference runs: One of three outcomes:
   • Success: Status => completed, webhook called with results
   • Failure: Status => failed, webhook called with error details
   • Busy: Status => pending (rollback), webhook called for retry notification

Webhook Notification API

When configured, the API sends HTTP POST requests to your webhook URL whenever an analysis status changes:

{
  "analysisId": "b57f1f77bcf86c23d799439011",
  "tenantId": "your-tenant-id",
  "name": "demo.jpg",
  "status": "completed",
  "timestamp": "2026-02-01T14:32:15.000Z",
  "resultClass": 1,
  "resultSubClasses": [2],
  "processingStartTime": "2026-02-01T14:30:00.000Z",
  "processingFinishTime": "2026-02-01T14:32:14.000Z"
}

Payload

The payload is sent JSON-encoded with the following fields:

Field	Type	Description
analysisId	string	MongoDB ObjectId of the analysis (as string)
tenantId	string	MongoDB ObjectId of the tenant (as string)
name	string	Name/filename of the analysis
status	enum	Current status: pending | processing | completed | failed
timestamp	string	ISO 8601 timestamp when the webhook was triggered
resultClass	number	Classification result: 0: real | 1: fake | 2: abstain | 3: uncertain
resultSubClasses	Array<number>	Sub-classification: 0: ai-generated | 1: ai-manipulated | 2: manipulated (empty set is allowed)
processingStartTime	string | null	ISO 8601 timestamp when processing started, or null
processingFinishTime	string | null	ISO 8601 timestamp when processing finished, or null

Request Details

We call the webhook URL like this:

Property	Value
Method	POST
Content-Type	application/json
User-Agent	Neuramancer-Webhook/1.0
Timeout	5 seconds

Important Notes

• Webhooks are called on status transitions: pending => processing, processing => completed/failed, and rollback scenarios
• Authentication is managed via presigned webhook URLs that tenants rotate according to their own security policies
• Webhook failures are logged but do not affect analysis processing

Status-based Processing

Filter by the status field in your webhook handler to process only the events you’re interested in, such as completed analyses.

Configuration

Manage webhooks by configuring the webhookUrl field in your tenant settings using the Tenant Management API.

Securing Webhooks

You can implement webhook security using query parameters or path segments in your webhook URL:

{
  "webhookUrl": "https://example.com/webhooks/neuramancer?token=your-secret-token"
}

Rotating Webhook Tokens

To rotate your webhook authentication token:

1. Generate a new token in your system
2. Update the webhook URL with the new token via PUT /v1/tenant
3. Old requests will fail authentication; new events use the new token

User-Agent Verification

All webhook requests include the following User-Agent header:

User-Agent: Neuramancer-Webhook/1.0

You can verify this header to ensure requests originate from the Neuramancer platform.