Webhooks

Webhooks provide real-time notifications when your document processing jobs complete, eliminating the need for continuous polling. This event-driven approach improves efficiency and reduces unnecessary API calls.

Setting Up Webhooks

Navigate to the Settings Panel
Locate the “Webhooks” section
Enter your webhook endpoint URL with an optional secret

We currently only support a single webhook per account.

Webhook reliability notes:

Webhooks are retried on 5xx errors and timeouts, but not on 4xx errors
Always implement idempotent webhook handlers using request_id to deduplicate
Set a reasonable server timeout — Datalab waits up to 30 seconds for your endpoint to respond

Per-Request Webhook Override

You can override the default webhook URL for specific API requests by including the webhook_url parameter:

import requests

url = "https://www.datalab.to/api/v1/convert"

form_data = {
    'file': ('document.pdf', open('document.pdf', 'rb'), 'application/pdf'),
    'output_format': (None, 'markdown'),
    'webhook_url': (None, 'https://your-custom-webhook.com/endpoint')
}

headers = {"X-API-Key": "YOUR_API_KEY"}

response = requests.post(url, files=form_data, headers=headers)

This is useful when:

Different projects need different webhook endpoints
You want to route notifications to specific services
Testing webhook integrations without changing account settings

The per-request webhook URL will be used instead of your account’s default webhook URL for that specific request only.

Webhook Payload

When a webhook is triggered, Datalab sends a POST request to your configured endpoint with a JSON payload containing the following fields:

{
  "request_id": "abc123",
  "request_check_url": "https://api.datalab.to/api/v1/convert/abc123",
  "webhook_secret": "your_configured_secret"
}

Field	Description
`request_id`	The unique identifier for the processing request
`request_check_url`	URL to retrieve the full results of the processed document
`webhook_secret`	Your configured webhook secret (if set)

Webhook Secret Verification

The webhook secret is included in the JSON request body, allowing you to verify that incoming webhooks are authentic requests from Datalab.

Verifying Webhooks on Your Server

Here’s an example of how to verify the webhook secret in your receiving endpoint:

from fastapi import FastAPI, Request, HTTPException
import os

app = FastAPI()

@app.post("/my-webhook")
async def receive_webhook(request: Request):
    data = await request.json()

    # Verify the webhook secret
    expected_secret = os.environ["DATALAB_WEBHOOK_SECRET"]
    received_secret = data.get("webhook_secret")

    if received_secret != expected_secret:
        raise HTTPException(status_code=401, detail="Invalid webhook secret")

    # Process the webhook
    request_id = data["request_id"]
    check_url = data["request_check_url"]

    # Fetch the full results using check_url...

The webhook secret is transmitted in plaintext within the request body. Ensure your webhook endpoint uses HTTPS to encrypt the data in transit. Avoid logging the full request body in production to prevent secret exposure.

Delivery Attempt History

Every webhook delivery attempt is recorded and visible in the Usage tab of the dashboard. Click any processed request to open the delivery drawer and see:

Timestamp of each delivery attempt
HTTP status code returned by your endpoint
Response body (truncated for large payloads)
Whether the delivery succeeded or is being retried

Use delivery history to diagnose missed events without adding logging to your own server.

Troubleshooting

Not Receiving Events If your webhook is not receiving events, try the following:

Verify URL is publicly accessible
Validate webhook secret matches
Check the delivery attempt history in the Usage tab for status codes and error details
Ensure your endpoint responds within 30 seconds

Duplicate Events We may send duplicate responses to a webhook endpoint. To handle this we recommend that you implement idempotency checks to ensure single processing.

Welcome

On-prem

Platform

Setting Up Webhooks

Per-Request Webhook Override

Webhook Payload

Webhook Secret Verification

Verifying Webhooks on Your Server

Delivery Attempt History

Troubleshooting

​Setting Up Webhooks

​Per-Request Webhook Override

​Webhook Payload

​Webhook Secret Verification

​Verifying Webhooks on Your Server

​Delivery Attempt History

​Troubleshooting

Setting Up Webhooks

Per-Request Webhook Override

Webhook Payload

Webhook Secret Verification

Verifying Webhooks on Your Server

Delivery Attempt History

Troubleshooting