Skip to main content
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

  1. Navigate to the Settings Panel
  2. Locate the “Webhooks” section
  3. Enter your webhook endpoint URL with an optional secret
We currently only support a single webhook per account.

​
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/marker"

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/marker/abc123",
  "webhook_secret": "your_configured_secret"
}
FieldDescription
request_idThe unique identifier for the processing request
request_check_urlURL to retrieve the full results of the processed document
webhook_secretYour 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.

​
Troubleshooting

Not Receiving Events If your webhook is not receiving events, try the following:
  • Verify URL is publicly accessible
  • Validate webhook secret matches
  • Check your server logs for 4xx errors (authentication, invalid endpoint, etc.)
  • 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.

​
Coming Soon

  • Project-specific webhooks