Webhook Integration

Webhooks allow your system to receive instant HTTP notifications when long-running asynchronous tasks (such as background responses, batch processing, or video generation) complete or transition states without continuous polling.

Webhook Architecture

[Job Completed / Failed] -> [Gateway Signs HMAC Payload] -> [HTTP POST to Your Endpoint] -> [Your Server Returns 200 OK]

Register Endpoint: Add your server URL and select subscribed events via the Webhooks Dashboard.
Store Secret: Secure the whsec_... signing secret generated upon creation.
Verify Signature: Validate the webhook-signature header on your server using the Standard Webhooks specification before processing payloads.

Configuring Webhooks via Dashboard

Webhook registration and lifecycle management are handled visually via the Webhooks Dashboard:

Sign in to your account and navigate to the Webhooks section in the dashboard.
Click Add Webhook.
Provide your server’s public Endpoint URL (must be a publicly accessible https:// or http:// destination).
Select the Events you want to receive (e.g., response.completed, batch.completed, video.completed).
Click Save and copy the generated Signing Secret (whsec_...). Save this secret in your server environment variables.
Use the Send Test button to dispatch a mock webhook.test event and confirm your endpoint handles deliveries with HTTP 200 OK.

The signing secret (whsec_...) is shown only once when creating an endpoint. If lost, delete the endpoint and create a new one to generate a new secret.

Supported Events

Category	Event ID	Trigger Condition
Responses	`response.completed`	Background response inference completed successfully
Responses	`response.failed`	Background response job encountered an error
Responses	`response.cancelled`	Background response cancelled by caller
Batch	`batch.completed`	All items in batch execution finished processing
Batch	`batch.failed`	Batch processing job failed
Batch	`batch.cancelled`	Batch job cancelled prior to completion
Video	`video.completed`	Video rendering finished and output asset is ready
Video	`video.failed`	Video rendering job failed

Payload Structure & Headers

Deliveries are dispatched as HTTP POST requests formatted as standard JSON conforming to Standard Webhooks:

{
  "object": "event",
  "id": "evt_4f8c1a2b3d4e5f60718293a4b5c6d7e8",
  "type": "response.completed",
  "created_at": 1750287018,
  "data": {
    "id": "resp_abc123"
  }
}

Every delivery includes three verification headers:

Header	Description
`webhook-id`	Unique delivery identifier. Use as an idempotency key for deduplication.
`webhook-timestamp`	Unix timestamp (seconds) when the payload was signed.
`webhook-signature`	HMAC SHA-256 signature of the raw payload.

Signature Verification Examples

Use the official standardwebhooks package to verify payload signatures before processing events:

import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();
const wh = new Webhook(process.env.NEOSANTARA_WEBHOOK_SECRET);

app.post('/api/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = wh.verify(req.body, {
      'webhook-id': req.header('webhook-id'),
      'webhook-timestamp': req.header('webhook-timestamp'),
      'webhook-signature': req.header('webhook-signature')
    });

    if (event.type === 'response.completed') {
      console.log('Completed response ID:', event.data.id);
    }

    res.status(200).send('OK');
  } catch (error) {
    res.status(400).send('Invalid signature');
  }
});

from fastapi import FastAPI, Request, HTTPException
from standardwebhooks.webhooks import Webhook
import os

app = FastAPI()
wh = Webhook(os.environ["NEOSANTARA_WEBHOOK_SECRET"])

@app.post("/api/webhooks")
async def handle_webhook(request: Request):
    raw_body = await request.body()
    headers = {
        "webhook-id": request.headers.get("webhook-id"),
        "webhook-timestamp": request.headers.get("webhook-timestamp"),
        "webhook-signature": request.headers.get("webhook-signature"),
    }
    try:
        event = wh.verify(raw_body, headers)
        if event["type"] == "response.completed":
            print("Completed response ID:", event["data"]["id"])
        return {"status": "ok"}
    except Exception:
        raise HTTPException(status_code=400, detail="Invalid signature")

Always verify the signature against the raw byte body before parsing into a JSON object to prevent byte order divergence.

Delivery Retries & Security

Immediate Acknowledgment (HTTP 2xx): Your server must acknowledge reception with HTTP 200 OK within seconds. Heavy computations should be deferred to internal workers.
Exponential Backoff Retries: If your server returns non-2xx codes or times out, the gateway retries delivery automatically with exponential backoff.
SSRF Guardrails: Loopback destinations (localhost, 127.0.0.1), private RFC 1918 subnets, and link-local targets are blocked by default.

Next Steps

Goal	Guide
Background Responses API	Background Jobs Execution
Batch Processing at scale	Batch Processing Guide
Asynchronous video rendering	Video Generation
Common questions & policies	FAQ & Questions

Guides

Operations & Security

Recursive Language Models (RLM)

Advanced AI Techniques

Webhook Architecture

Configuring Webhooks via Dashboard

Supported Events

Payload Structure & Headers

Signature Verification Examples

Delivery Retries & Security

Next Steps

​Webhook Architecture

​Configuring Webhooks via Dashboard

​Supported Events

​Payload Structure & Headers

​Signature Verification Examples

​Delivery Retries & Security

​Next Steps

Webhook Architecture

Configuring Webhooks via Dashboard

Supported Events

Payload Structure & Headers

Signature Verification Examples

Delivery Retries & Security

Next Steps