Note: This article assumes you already are familiar with Parseur basics and have already set up mailboxes and parsing templates. Check out this page should you need to get started.
What is a webhook?
A webhook is used by application developers and programmers to exchange 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 data extracted text formatted 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 popup page will appear:
Step 2: Select the trigger event
The trigger event determines when to send a webhook and how the payload looks like.
You can choose between:
Document processed: this is the default and what you need, most of the time. 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 there was 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 to. Use an HTTPS URL to encrypt your data as it transits between servers.
Tip: while developing your integration, the following website is great for testing your webhooks: https://webhook.site.
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 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: https://api.example.com/articles/{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 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 on the mailbox where you created it (and paused in all the other ones).
This allows you to easily activate and edit the target URL of a webhook across all your mailboxes.
Delete a webhook
You can delete a webhook by clicking on the red trash icon.
Note: deleting a webhook will delete 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: 35.204.12.29
Add this IP address to the whitelist of your application firewall to allow incoming webhooks from Parseur.
Failed webhook automatic retries
All failed webhooks are re-tried up to 5 times (so 6 tries maximum). A failed webhook means the endpoint replied with:
HTTP status 408 (server timeout)
HTTP status 429 (too many requests)
HTTP status in the 500 to 599 range (server error)
Connection Timeout (timeout when trying to connect to the server)
Of note, a webhook will NOT be retried in case of a Read Timeout (i.e. connection to the server succeeded but Parseur didn't receive any reply) because Parseur has no way of knowing if the request succeeded or not.
The first retry happens 1 minute after the initial reply. The next retries are attempted 4, 9, 16, then 25 minutes after each other. This mechanism is called exponential back-off and prevents overloading the receiving service with requests.
This applies to all webhooks, including custom webhooks and Zapier, Make and Power Automate integrations. All actions and retries (if any) are visible in the documents' log.
Note for PHP users:
Parseur sends data encoded as JSON in a POST request to your server. This means that you can not get the data from the $_POST variable, and have to use php://input instead, as described here: https://www.php.net/manual/en/wrappers.php.php#wrappers.php.input