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

This webhook tab in Parseur 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 text field 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:

webhook.site
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.

A screenshot of Parseur's document list page with the Logs button highlighted

A screenshot of Parseur's document view page with the Logs button highlighted

Click on show details to view additional information, such as payload or error messages for individual events.

A screenshot of Parseur's document logs page

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.