Prerequisites: This guide assumes you are familiar with Parseur basics and have already set up mailboxes. If you need help getting started, check out our Getting Started page.
What is a webhook?
A webhook is a way for applications to send and receive data between servers via HTTP POST requests. Think of it as an event notification sent directly from one application to another when a specific event occurs.
In Parseur, webhooks can be triggered by various events, such as when a new document is received. The extracted data is sent as JSON.
Step 1: Open the Webhook Tab in the Export section
To set up your webhook in Parseur:
Open a mailbox.
Click on the Download / Export section on the left menu.
Click on the Webhook tab.
Click the New webhook button.
The following dialog opens:
Step 2: Select the Trigger Event
The trigger event defines when the webhook is sent and what data is included.
You can choose from:
Document Processed (default): Triggered when a document is processed. The payload format matches the “view as JSON” option.
Document Processed (Flattened): Available if your mailbox includes table fields. It flattens data, useful for endpoints that don’t support deep JSON structures.
Template Needed: Triggered when a document fails to process (status: “New Template Needed”). It is useful to notify your systems and teams of parsing issues. Parseur will also send an email for this event.
Export Failed: Triggered when another webhook or automated export fails. The payload includes a
textfield that allows this event to be directly sent as a Slack notification.Table Item Processed: Available when using table fields. You will need to select te table you want this trigger to be based on. Sends data as a JSON array of items (one row per table field item)
Step 3: Enter the Target URL
Enter the URL where you want to send the POST request. Ensure it’s an HTTPS URL to secure data in transit.
For testing your webhooks, you can use:
beeceptor.com (allows you to change the HTTP response codes)
Using Basic Authentication
If the target URL requires authentication, format it as https://user:[email protected]/your-api-url. Credentials will be encoded in base64 and sent with the request. Always use HTTPS to keep this information secure.
Making the URL dynamic using values from parsed results in URL
You can dynamically include parsed field values in the URL using {field_name}.
For example, use https://api.example.com/articles/{article_id} to append article_id to the URL.
You can enter several fields in the URL this way.
Step 4: Choose a Name (Optional)
Assign a name to your webhook to easily identify it later.
Step 5: Customize headers (optional)
If your webhook requires specific HTTP headers (e.g., authorization tokens), add them here. For example, to add an authorization token:
X-Authorization: abc-123456-789
You can add multiple headers, one per line.
Note: The Content-Type header is automatically set to application/json by Parseur.
Step 6: Create the Webhook
Click the Create button to save your webhook configuration.
You can create multiple webhooks for different triggers.
Step 7: Test Your Webhook and Check the Logs
To test your webhook, you can:
Send a new document.
Reprocess an existing document (reprocessing an already-processed document doesn't use more credits).
Check the document status in Parseur:
Processed: The document was successfully extracted and the webhook was sent.
Export Failed: There was an issue sending the document.
To view the logs:
Go to the document list or document view.
Click the file with a magnifying glass icon (🔎) to open the logs page.
Click on show details to view additional information, such as payload or error messages for individual events.
Manage Your webhooks
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.
Parseur IP address used for sending webhooks
Webhooks are sent from IP 35.204.12.29. Add this IP to your firewall whitelist to receive webhooks from Parseur.
"export failed" error: troubleshoot your webhooks
If you encounter “Export failed” status, refer to our webhook troubleshooting guide for help.
Note for PHP users:
Parseur sends JSON-encoded data via POST requests. Access the data using php://input, not $_POST. More details here.