How to Use Webhooks to Integrate PDFXINET with Your Apps

What Is a Webhook?

A webhook is an HTTP callback: instead of your application repeatedly asking "is the file ready yet?", PDFXINET pushes a notification to your server the moment processing finishes. This eliminates polling, reduces latency, and keeps your integration simple.

Prerequisites

• A Pro or Business PDFXINET plan (API access required).
• An API token — generate one from your Profile page and pass it as the X-API-Token header on every API request.
• A publicly reachable HTTPS endpoint on your server that can accept POST requests.

Registering Your Webhook URL

POST /api/v1/webhooks
X-API-Token: your-token-here
Content-Type: application/json

{"url": "https://yourapp.example.com/hooks/pdfxinet"}

A successful response returns {"ok": true, "webhook_url": "https://..."}. Only one webhook URL is stored per user — calling this endpoint again replaces the previous URL.

The file.processed Payload

Every time a conversion completes, PDFXINET sends a POST request to your endpoint with this JSON body:

{
  "event":         "file.processed",
  "entry_id":      "uuid-of-history-entry",
  "original_name": "report.docx",
  "filename":      "abc123.pdf",
  "extension":     "pdf",
  "size_bytes":    204800,
  "user_id":       "uuid-of-your-account"
}

Testing Your Integration

POST /api/v1/webhooks/test
X-API-Token: your-token-here

This fires a test event to your registered URL immediately. Use it to verify your endpoint is reachable and handling payloads correctly before running real conversions.

Retrieving and Removing the Webhook

# Get current URL
GET /api/v1/webhooks

# Remove webhook
DELETE /api/v1/webhooks

Security Recommendations

• Verify user_id — always check that the user_id in the payload matches your PDFXINET account ID before processing the event.
• Use HTTPS — webhook payloads travel over the public internet; plaintext HTTP endpoints should never be used in production.
• Idempotency — deliveries are best-effort. Design your handler to be idempotent: storing the entry_id and skipping duplicates is a safe approach.
• Respond quickly — PDFXINET's webhook thread has a 10-second timeout. Return HTTP 200 immediately and process the payload asynchronously if needed.