Get data using webhooks

Webhooks are the fastest, most reliable way to get your parsed data. As soon as a document is processed, Parseur sends an HTTP POST to your endpoint with the extracted JSON.

If webhooks aren’t an option (e.g., no public endpoint, restricted network, or policy constraints), see Get data using alternative methods.

What are webhooks?

Parseur processing is asynchronous: a successful upload confirms receipt, not completion.

A webhook is a URL you register on a mailbox. When a chosen event occurs (e.g., document processed), Parseur makes a POST call to that URL with the extracted data in the request body.

Use webhooks to automatically receive results and trigger downstream actions in your system. You’ll configure the webhook once; Parseur handles the rest (details below).

Quick testing:

https://webhook.site

https://beeceptor.com (lets you simulate different response codes)

Going to production but unsure what to use? Consider Cloudflare Workers for a simple, scalable HTTPS endpoint suited for webhooks.

How webhooks work

Trigger: An event occurs (e.g., a document is processed), and Parseur sends a POST with a JSON payload to your URL.

Acknowledge: Your endpoint should respond with a 2xx status within 30 seconds.

Delivery: Non‑2xx or timeouts are considered failures and may be retried (see Delivery & retries below).

Event types

Choose a trigger when creating a webhook:

Document Processed (default): Fires when a document is processed. Payload matches the View as JSON output for that document.

Document Processed (Flattened): If your mailbox has table fields, this flattens table data for systems that don’t support nested JSON.

Table Item Processed: Sends the table rows as a JSON array, one item per row.

Process failed: Fires when a document can’t be parsed.

Export Failed: Fires when another export (webhook or automation) fails; includes error details so you can alert teams or tools.

Payload format

The payload contains the extracted fields from your document (including any Metadata Fields you added).

For Document Processed (Flattened), table fields are flattened; for Table Item Processed, the body is an array of items.

Example payload (simplified)

{
  "order_id": "12345",
  "total": 199.99,
  "items": [
    {"sku": "ABC", "qty": 2},
    {"sku": "XYZ", "qty": 1}
  ],
  "DocumentID": "1e2e34cba5c678a9012f3e456c789a0f"
}

Actual keys depend on your mailbox schema and Metadata Fields.

For PHP users: Parseur sends JSON-encoded data via POST requests. Access the data using php://input, not $_POST. More details here.

Request headers

Every webhook request includes the following headers:

Header	Description
`Content-Type`	Always `application/json`.
`X-Parseur-Document-Id`	The ID of the document that triggered the webhook. Same value as the `DocumentID` field in the payload.

The X-Parseur-Document-Id header lets you identify the document without parsing the body. This is useful to:

Deduplicate deliveries: retries and reprocessing send the same document ID, so you can detect requests you already handled.

Route or log requests early: for example, in a gateway, proxy, or queue that only inspects headers.

Correlate with Parseur: use the ID to look up the document via the API or in the app.

Any custom headers you configure on the webhook are sent in addition to these.

Configure a webhook

Create a webhook

Open a mailbox → Download / Export → Webhook → New webhook.

Pick a Trigger (see above).

Enter your Target URL (HTTPS strongly recommended).

(Optional) Dynamic URL: insert field values with {field_name}, e.g., https://api.example.com/orders/{order_id}.

(Optional) Headers: add custom headers like X-Authorization: abc123.

(Optional) Basic auth: you may include credentials in the URL (https://user:pass@api.example.com/...).

Click Create, then test by sending a new document or reprocessing an existing one.

Pause / Activate a Webhook

Click the ⏸️ pause icon to temporarily stop a webhook and the ▶️ play icon to reactivate it.

This is useful when switching between development and production servers or when making server changes.

Manage Webhooks Across Mailboxes

Webhooks are visible across all mailboxes but can be activated and paused separately for each mailbox

Changing a webhook URL or configuration will impact all mailbox using the webhook

This allows easy management and target URL adjustments across your mailboxes.

Delete a webhook

Click the red trash icon to delete a webhook.

Deleting a webhook removes it from all mailboxes. If you only want to stop it for one mailbox, use the pause option instead.

Manage your webhooks using the API

Check out the Endpoints → Webhooks section if you want to create, delete, activate, deactivate webhooks programmatically using the API.

Test & observe

For quick testing, you can point the webhook to tools like webhook inspectors like https://webhook.site or https://beeceptor.com.

Use the 🔍 Logs (magnifying glass icon) from the document list or document view to see each webhook attempt, payload, response code, and error details.

Reprocess a document to resend all exports without consuming extra credits.

Delivery & retries

Timeout window: Parseur waits up to 30 seconds for your response. Customers on Enterprise plans can contact us to request an increased timeout.

Automatic retries: On failure, Parseur retries up to 5 times (6 attempts total) with exponential backoff (≈1, 4, 9, 16, 25 minutes).

When it retries: connection timeout, HTTP 408, 429, or 5xx.

When it won’t: other HTTP codes or a read timeout (connection succeeded but no response).

Operational tip: Design your endpoint to be idempotent (safe on duplicate deliveries), for example by using the X-Parseur-Document-Id header as a deduplication key. Reply 2xx quickly and do heavy work asynchronously.

Security & networking

Always use HTTPS.

Prefer an auth header (e.g., API key) over credentials in URLs.

If you filter by IP, webhooks originate from 35.204.12.29.

Keep endpoints lightweight; acknowledge fast, process later.

Quick reference

Prefer Webhooks for real-time, push-based delivery.

Aknowledge fast with 2xx, do heavy processing later.

Stay within Rate limits.

What are webhooks?#

How webhooks work#

Event types#

Payload format#

Request headers#

Configure a webhook#

Create a webhook#

Pause / Activate a Webhook#

Manage Webhooks Across Mailboxes#

Delete a webhook#

Manage your webhooks using the API#

Test & observe#

Delivery & retries#

Security & networking#

Quick reference#

What are webhooks?

How webhooks work

Event types

Payload format

Request headers

Configure a webhook

Create a webhook

Pause / Activate a Webhook

Manage Webhooks Across Mailboxes

Delete a webhook

Manage your webhooks using the API

Test & observe

Delivery & retries

Security & networking

Quick reference