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 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 pop-up 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.
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 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: 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 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: 35.204.12.29
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 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