Note: This article assumes you already are familiar with Parseur basics and have already set up a 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 let 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 doesn'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 such endpoint to automatically notify your systems there was a problem with parsing (Parseur can also send an email for such 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. Make sure 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.
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. 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.
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:
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 webhook 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, 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 webhook from a single IP:
Add this IP address to the whitelist of your application firewall to allow incoming webhooks from Parseur.
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