Direct Webhooks

For production applications, use Svix webhooks instead. Svix provides cryptographic signing, advanced retries, and a debugging dashboard. Direct webhooks are best for prototyping or simple internal integrations.

Direct webhooks send HTTP POST requests directly to your endpoint when jobs complete. Reducto retries failed deliveries up to 3 times with exponential backoff.

Testing with webhook.site

For quick testing, use webhook.site to get a temporary endpoint URL. It shows you the exact payload Reducto sends.

Submitting jobs

Include your webhook URL in the async configuration:

from reducto import Reducto

client = Reducto()

job = client.parse.run_job(
    input="https://example.com/document.pdf",
    async_={
        "webhook": {
            "mode": "direct",
            "url": "https://your-app.com/webhook"
        },
        "metadata": {
            "user_id": "123",
            "document_type": "invoice"
        }
    }
)
print(f"Job ID: {job.job_id}")

import Reducto from "reductoai";

const client = new Reducto();

const job = await client.parse.runJob({
  input: "https://example.com/document.pdf",
  async: {
    webhook: {
      mode: "direct",
      url: "https://your-app.com/webhook"
    },
    metadata: { userId: "123", documentType: "invoice" }
  }
});

curl -X POST https://platform.reducto.ai/parse_async \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "https://example.com/document.pdf",
    "async": {
      "webhook": {"mode": "direct", "url": "https://your-app.com/webhook"},
      "metadata": {"user_id": "123"}
    }
  }'

Works with all async endpoints: /parse_async, /extract_async, /split_async, /pipeline_async.

Webhook payload

When the job completes, your endpoint receives:

{
  "status": "Completed",
  "job_id": "204a39e4-dd10-4c83-a978-0cee4af8cde2",
  "metadata": {
    "user_id": "123",
    "document_type": "invoice"
  }
}

The status is either Completed or Failed. Use job_id to retrieve results with client.job.get().

Handling webhooks

from flask import Flask, request, jsonify
from reducto import Reducto

app = Flask(__name__)
client = Reducto()

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.json
    
    if payload['status'] == "Completed":
        job = client.job.get(payload['job_id'])
        # Process job.result
        print(f"Processed job: {payload['job_id']}")
    
    return jsonify({"received": True}), 200

import express from 'express';
import Reducto from "reductoai";

const app = express();
const client = new Reducto();

app.use(express.json());

app.post('/webhook', async (req, res) => {
  const { job_id, status } = req.body;
  
  if (status === "Completed") {
    const job = await client.job.retrieve(job_id);
    // Process job.result
    console.log(`Processed job: ${job_id}`);
  }
  
  res.status(200).json({ received: true });
});

Validating requests

Since direct webhooks lack cryptographic signing, validate requests using a secret token in metadata:

import os
from flask import Flask, request, jsonify, abort
from reducto import Reducto

app = Flask(__name__)
client = Reducto()
WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]

# When submitting jobs, include the secret
def submit_job():
    return client.parse.run_job(
        input="https://example.com/document.pdf",
        async_={
            "webhook": {"mode": "direct", "url": "https://your-app.com/webhook"},
            "metadata": {"secret": WEBHOOK_SECRET, "user_id": "123"}
        }
    )

# When handling webhooks, verify the secret
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.json
    
    # Validate secret
    if payload.get('metadata', {}).get('secret') != WEBHOOK_SECRET:
        abort(401)
    
    if payload['status'] == "Completed":
        job = client.job.get(payload['job_id'])
        # Process job.result
    
    return jsonify({"received": True}), 200

import express from 'express';
import Reducto from "reductoai";

const app = express();
const client = new Reducto();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;

app.use(express.json());

// When submitting jobs, include the secret
async function submitJob() {
  return client.parse.runJob({
    input: "document.pdf",
    async: {
      webhook: { mode: "direct", url: "https://your-app.com/webhook" },
      metadata: { secret: WEBHOOK_SECRET, userId: "123" }
    }
  });
}

// When handling webhooks, verify the secret
app.post('/webhook', async (req, res) => {
  // Validate secret
  if (req.body.metadata?.secret !== WEBHOOK_SECRET) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  
  if (req.body.status === "Completed") {
    const job = await client.job.retrieve(req.body.job_id);
    // Process job.result
  }
  
  res.status(200).json({ received: true });
});

Troubleshooting

Webhook not received

Verify your endpoint URL is publicly accessible (not localhost)
Ensure your endpoint returns 2xx status codes
Check your server logs for incoming requests

Webhook received but job retrieval fails

Job IDs expire after 12 hours. Retrieve results promptly after receiving the webhook.

Duplicate webhooks received

Reducto retries failed deliveries. Make your handler idempotent by tracking processed job IDs.

Best practices

Use HTTPS for your webhook endpoint
Validate requests using the token-in-metadata pattern
Return quickly: Return 2xx immediately, process results asynchronously
Be idempotent: Handle duplicate deliveries gracefully
Log everything: Direct webhooks have no dashboard, so log for debugging

For production applications with reliability requirements, use Svix webhooks.

Get Started

Developer Tools

Core Functions

Workflows and Pipelines

Configurations

Reference

Components

Enterprise Resources

Security and privacy

On-premise Resources

Direct Webhooks

Testing with webhook.site

Submitting jobs

Webhook payload

Handling webhooks

Validating requests

Troubleshooting

Best practices

​Testing with webhook.site

​Submitting jobs

​Webhook payload

​Handling webhooks

​Validating requests

​Troubleshooting

​Best practices

Testing with webhook.site

Submitting jobs

Webhook payload

Handling webhooks

Validating requests

Troubleshooting

Best practices