A serious webhooks implementation for serious document pipelines

Submit to Mathpix with a callback URL

• callback_url: your webhook endpoint URL, where we send this submission’s notifications.
• callback_events: selects which events you receive, such as document completed (including any requested conversion results) or document batch completed. Optional.
• callback_headers: headers we include on each notification with content of your choice. Optional.

# Example request (cURL; any tool that sends HTTP requests works the same way)
curl -X POST https://api.mathpix.com/files/v1/uri \
-H 'app_key: APP_KEY' \
-H 'Content-Type: application/json' \
--data '{
  "source_uri": "https://cdn.mathpix.com/examples/cs229-notes1.pdf",
  "callback_url": "https://your-app.example.com/mathpix/webhook",
  "callback_events": ["file.completed", "file.error"],
  "callback_headers": { "Authorization": "Bearer YOUR TOKEN" }
}'

# Example: submit a document with a callback
from mpxpy.mathpix_client import MathpixClient

client = MathpixClient(app_id="your-app-id", app_key="your-app-key")

client.file_new(
    source_uri="https://cdn.mathpix.com/examples/cs229-notes1.pdf",
    callback_url="https://your-app.example.com/mathpix/webhook",
    callback_events=["file.completed", "file.error"],
)

The webhook endpoint handler

• Answer with HTTP status 200 as soon as the notification is read, and do the work afterward. Any server error, or an answer that takes too long, counts as a failed attempt and starts the retries.
• Verify that the notification came from Mathpix before trusting the body. Every notification is signed with your signing secret, in the Mathpix-Signature header, and anything older than five minutes should be rejected.
• Deduplicate. Delivery is at least once, so the same notification can arrive more than once. Skip a duplicate notification by matching on:
  • event plus file_id for file.completed and file.error
  • event plus job_id for job.completed.

{
  "event": "file.completed",
  "file_id": "b1c9c3a8-55e4-4a09-b7d0-218ba5de4c4d",
  "status": "completed",
  "num_pages": 30,
  "num_pages_completed": 30
}

# Example: the handler that receives, verifies, and acts on notifications
from flask import Flask, abort, request
from mpxpy.mathpix_client import MathpixClient
from mpxpy.webhooks import verify_signature

# Mathpix API client, for accessing your results
client = MathpixClient(app_id="your-app-id", app_key="your-app-key")
SIGNING_SECRET = client.webhook_config_get().signing_secret

# Server for handling webhook notifications
application = Flask(__name__)

@application.post("/mathpix/webhook")
def mathpix_webhook():
    # Verify the notification came from Mathpix
    if not verify_signature(request.headers.get("Mathpix-Signature", ""), request.get_data(), SIGNING_SECRET):
        abort(400)
    # Hand the notification to your queue and answer right away
    enqueue(request.get_json())
    return "", 200

def notification_key(notification):
    # Key to check for duplicate notifications
    identifier = "job_id" if notification["event"] == "job.completed" else "file_id"
    return notification["event"], notification[identifier]

def process_notification(notification):
    # What your worker runs, one notification at a time
    key = notification_key(notification)
    if is_already_processed(key):
        return
    # Processing file.completed results the same as before.
    if notification["event"] == "file.completed":
        file_id = notification["file_id"]
        result = client.file_get(file_id)
        markdown_text = result.to_md_text()
    record_processed(key)

Note on request volume

Learn more