How to Manage Webhooks in RealScan | Reality Defender

RealScan can notify your systems via HTTP webhooks when a media scan finishes processing. This article describes the webhook interface for implementers building a receiver.

When a scan completes, RealScan sends an HTTP POST to each configured URL with a JSON payload that identifies the completed scan by requestId. To retrieve full scan details including status, uploader, scores, and related metadata, call the Media Detail API using that requestId and your API key.

Who can manage webhooks

All RealScan roles (Viewer, Contributor, and Admin) can view your organization's webhooks. Only Admin users can add or remove webhooks.

If you don't see the Webhooks menu or the Add webhook button, contact your organization admin to confirm your role.

Prerequisites

Before setting up a webhook, ensure the following are in place:

Active account: Your organization must have an active account on the Reality Defender platform with access to RealScan.
HTTPS endpoint: Your receiver URL must use HTTPS with a valid, publicly trusted TLS certificate.
API key: You need a Reality Defender API key to retrieve the full scan result.

Note: You do not need an API key to add a webhook URL in the web UI. You only need it when your receiver calls the Media Detail API after it receives a webhook event.

Set up a webhook

Sign in to RealScan.
In the left sidebar, select Webhooks.
Click Add webhook and enter the HTTPS URL that should receive notifications.
Click Save. The webhook appears in the list and begins receiving events immediately.

All configured RealScan webhook URLs for the organization are notified when scans complete.

Note: The URL must be a valid HTTPS endpoint. HTTP URLs are not accepted.

Delivery

Each delivery is a single HTTP POST request.

Property	Value
Method	POST
Content-Type	`application/json`
Success	Any `2xx` response status
Failure	Any non-`2xx` status, timeout, or connection error

Failed deliveries may be retried a small number of times. Your endpoint should respond 2xx as soon as it accepts the payload and perform any slow processing asynchronously.

Headers sent with every delivery

Header	Description
Content-Type	Always `application/json`
Accept	`application/json, text/plain, /`
User-Agent	HTTP client identifier. This is an implementation detail; do not hard-depend on this value.

RealScan webhooks do not currently send a signature header or an X-API-Key header on delivery.

Payload format

The request body is a JSON object with a single field:

{   "requestId": "3cc6df30-0142-41be-8cb0-f70be996e0cd" }

Field	Type	Description
requestId	string (UUID)	Identifier of the completed scan. Use this value with the Media Detail API to fetch the full result.

The webhook body does not include overall status, conclusion, score, uploader identity, organization ID, filename, or media type.

Fetching the full scan result

After receiving a webhook event, you can retrieve scan details with the Media Detail API:

curl -X GET \   
"<https://api.prd.realitydefender.xyz/api/media/users/${REQUEST_ID}>" \   
-H "X-API-KEY: your-api-key" \   
-H "Content-Type: application/json"

Fields commonly useful for usage monitoring and auditing include:

Field	Description
requestId	Scan ID. This is the same value sent in the webhook.
userId	User ID of the uploader.
institutionId	Organization ID.
originalFileName	Original uploaded filename.
mediaType	IMAGE, VIDEO, AUDIO, or TEXT.
uploadedDate	Upload timestamp in ISO 8601 format.
overallStatus	Overall result status.
resultsSummary	Ensemble status, score, and errors.

Recommended integration pattern

Receive the RealScan webhook and read requestId.
Respond with 2xx promptly.
Call Media Detail with that requestId and your API key.
Persist or forward the fields required by your monitoring, auditing, or identity systems.

Example receiver

The following pseudocode shows a basic Flask receiver that accepts the webhook, retrieves the full Media Detail response, and returns a success status.

from flask import Flask, request 
import requests  

app = Flask(__name__) 
RD_API_KEY = "your-api-key"
  
@app.post("/webhook/realscan") 
def realscan_webhook():     
    body = request.get_json(force=True)     
    request_id = body["requestId"]    
  
    detail = requests.get(         
        f"<https://api.prd.realitydefender.xyz/api/media/users/{request_id}>",
        headers={"X-API-KEY": RD_API_KEY},
        timeout=30,
    ).json()      

    # Use detail["userId"], detail["institutionId"], detail["overallStatus"], etc.
    return "", 204

Note: For production receivers, validate the request structure, handle API errors, and move slow processing to an asynchronous job so the webhook response stays fast.

Remove a webhook

On Webhooks > RealScan, find the webhook you want to remove.
Click the trash icon next to it.
Confirm the deletion. RealScan removes the webhook immediately and stops sending events to that URL.

Deletion is permanent. To re-enable notifications to the same URL, add it again as a new webhook.

Need help?

Chat: Send a message to support using the bot in the bottom right corner
Email: support@realitydefender.com