Skip to main content
All CollectionsExporting data
Send parsed data using Webhooks
Send parsed data using Webhooks

How to use webhooks to send parsed data to your servers and services in real time.

Updated over a week ago

Note: This article assumes you are already familiar with Parseur basics and have already set up mailboxes and parsing templates. Check out this page if you need to get started.

What is a webhook?

Developers and programmers of applications use a webhook to send and receive data between applications and servers. In technical terms, a webhook is an HTTP callback. It is an HTTP POST that gets triggered when something happens. You can view webhooks as a simple event notification via HTTP POST.

In Parseur, a webhook can be triggered when a new document is received and over various types of events. Parseur sends the extracted data as JSON.

Step 1: Open the "create webhook" page

To set up your webhook in Parseur:

  • Open a mailbox

  • Go to the Export section (on the left menu)

  • Click the Webhook tab

  • Click the Create a new webhook button

A pop-up page will appear:

Step 2: Select the trigger event

The trigger event determines when to send a webhook and what the payload looks like.

You can choose between:

  • Document processed: this is the default and what you need most of the time. The payload format is the same as when viewing the document and clicking on "view as JSON".

  • Document processed (flattened): this choice will only be available if you use table fields in your mailbox. It is useful for endpoints that don't support deep JSON structures, as it will "flatten" your table fields.

  • Template needed: this event is triggered when a document fails to process (status = "New Template Needed"). It can be useful to set up an endpoint to automatically notify your systems that there is a problem with parsing. Parseur can also send an email for such an event.

  • Table item processed: this choice will only be available if you use table fields in your mailbox. When selected, you'll have to choose the table field it relates to. Use this event to send the data as a JSON array of items (one row per table field item, non-table field items repeated on each row).

Step 3: Enter the target URL

The target URL is the URL where you want to POST your data. Make sure to use an HTTPS URL to encrypt your data as it transits between servers.

While developing your integration, the following website is great for testing your webhooks:

Using Basic Authentication

If your target is protected by Basic Authentication, you can add it in the form of https://user:[email protected]/your-api-url and credentials will be sent. The user name and password will be encoded into a base64 sequence before being sent to the server. This encoding is easily reversible, so make sure to use HTTPS to secure the credentials from eavesdropping.

Making the URL dynamic using values from parsed results in URL

You can include values from your parsed result in the URL using the {field_name} convention.

For example, let's say that you have a field called article_id and want to append that id at the end of your webhook. Enter the following as the target URL:{article_id}

You can enter several fields in the URL this way.

Step 4: Choose a Name (optional)

You can name this webhook to make it easier for you to remember where the data is sent to.

Step 5: Customize headers (optional)

If your webhook needs specific HTTP headers (like, for example, an authorization token), add them here. For example, if you need to add the token abc-123456-789 to the X-Authorization header, enter the following into the box:

X-Authorization: abc-123456-789

If you need to add several headers, enter one per line.

Note: you don't need to add the Content-Type header, Parseur will automatically add it for you (set to application/json)

Step 6: Create the webhook

Click the "Create" button to create the webhook.

You can create as many webhooks for as many triggers as you want.

Step 7: Test your webhook and check the logs

To test your webhook, you can either:

  • send a new document

  • or reprocess an existing one

Then check the document status on Parseur:

  • Processed means your document was correctly extracted and the webhook was successfully sent

  • Export Failed means there was a problem while sending your document

Access the logs to see the details:

  • Go to the document list or document view

  • Click on the πŸ”Ž magnifying glass icon, it will open the logs page

  • The logs will tell you the story of events for a document

  • Click on an event to view the details, such as the payload or the error message

Manage your webhooks

Pause / Activate a webhook

You can temporarily put a webhook on pause just by clicking on the pause icon, and reactivate it by clicking the play icon. This is useful if you want to make some changes to your server and pause webhooks in the meantime. It is also useful if you want to switch between your development and production servers.

Manage webhooks across different mailboxes

You can easily manage your webhooks across your mailboxes. When you create a webhook, it will be visible in all your mailboxes. By default, the created webhook is only activated in the mailbox where you created it (and paused in all others).

This makes it easy to turn on a webhook and change its target URL across all of your mailboxes.

Delete a webhook

You can delete a webhook by clicking on the red trash icon.

Note: deleting a webhook will remove it from all your mailboxes. If you want to remove a webhook from only one mailbox and not others, pause it.

Parseur IP address used for sending webhooks

Parseur sends a webhook from a single IP:

Add this IP address to the whitelist of your application firewall to allow incoming webhooks from Parseur.

"export failed" error: troubleshoot your webhooks

Getting "export failed" status for some documents? Check out the following article on how to troubleshoot and fix export failed webhook error.

Note for PHP users:

Parseur sends data encoded as JSON in a POST request to your server. This means that you cannot get the data from the $_POST variable and have to use php://input instead, as described here:

Did this answer your question?