Receiving Results with Webhooks
Have DocuPipe call your system the moment a document finishes processing, instead of checking back for results.
A webhook is a URL you own that DocuPipe calls when something finishes. Instead of your system asking us "is it done yet?", we send it an HTTP POST with the result as soon as the work completes.
This is the recommended way to run DocuPipe in production, and it is how automation platforms like Make.com, n8n and Power Automate get results back from us.
Where to set it up
The webhook portal lives in your DocuPipe account:
- Go to Settings, General tab.
- In the Developers card, find the Webhooks row and click Open Portal. The portal opens inside DocuPipe.
- Click Add Endpoint.
- Paste the URL that should receive the events, and select the event types you want it to receive.
Your endpoint URL must be HTTPS and reachable from the public internet.
This article describes the portal on DocuPipe's hosted service. Self-hosted and on-premise deployments run a simpler built-in portal with the same endpoints and events, but some of its controls are named differently and a few, such as the testing tab, are not available.
If you select no event types at all, the endpoint receives every event. That is convenient for a first test, but narrow it down afterwards so your handler only gets the events it actually acts on.
Which events to subscribe to
Every stage of processing emits a success event and an error event. Most integrations need only these two:
| Event | Fires when |
|---|---|
document.processed.success | Parsing of an uploaded document finished. The payload carries the document id, job id, filename, page count and parsed text. |
standardization.processed.success | A Standardization finished. The payload carries the extracted data itself, so most integrations can act on this event alone. |
The complete set of event types:
| Stage | Success | Error |
|---|---|---|
| Parsing | document.processed.success | document.processed.error |
| Extraction | standardization.processed.success | standardization.processed.error |
| Transformation | transformation.processed.success | transformation.processed.error |
| Classification | classification.processed.success | classification.processed.error |
| Splitting | split.processed.success | split.processed.error |
| Merging | merge.processed.success | merge.processed.error |
| Schema creation | schema.processed.success | schema.processed.error |
| Visual review | review.processed.success | review.processed.error |
| Workflow | workflow.processed.success | workflow.processed.error |
Two further events fire when a person acts on a visual review rather than when processing finishes: review.verified.success and review.rejected.success.
If you upload with a Workflow attached, every step in the workflow fires its own events as it completes, so a classify-then-extract pipeline reports both stages.
When a result is too large to deliver
On a very large document the parsed text or the extracted data can exceed the size we can deliver in a single message. We then send the event without the oversized field and set a flag in its place, and your handler fetches the full result from the API:
| Flag on the event | What to call |
|---|---|
textTooBig | GET /document/{documentId} |
dataTooBig | GET /standardization/{standardizationId} |
Handling these two flags is worth building in from the start. An integration that ignores them silently records an empty result on exactly the largest documents.
What your endpoint has to do
- Return a
2xxstatus within about 15 seconds. Anything else counts as a failure and we retry. - Do the slow work after acknowledging. If your handler writes to a database or calls another service, accept the message first and process it in the background.
- Turn off automatic CSRF protection on that route. The request comes from DocuPipe, not from a browser session.
Failed deliveries are retried with increasing gaps for just over 27 hours before we give up on a message. An endpoint that fails every attempt for five consecutive days is disabled automatically, and you re-enable it from the portal.
Testing before you go live
Each endpoint in the portal has a Testing tab that sends a simulated event to your URL. The ids in it are fake, but the structure and headers match real traffic, so it is enough to confirm your handler parses the payload and answers correctly.
Using a webhook from Make.com, n8n or Power Automate
The pattern is the same on all three:
- In the automation platform, add its custom webhook trigger and copy the URL it generates.
- Paste that URL into a new endpoint in the DocuPipe webhook portal and subscribe it to the events you care about.
- Leave the platform listening, then run one document through DocuPipe. Most platforms use that first real message to learn the payload structure, which is what lets you map fields in the following steps.
- Build the rest of the scenario against the fields from that message.
The Make.com integration guide walks through a complete scenario end to end.
When nothing arrives
Open the endpoint in the portal and look at its delivery log. It records every attempt, the response your server returned, and the payload we sent, which separates the two possible problems: we never delivered, or we delivered and your endpoint rejected it.
From there you can resend an individual message, or use Recover failed messages to replay everything that failed after a chosen time.
Three causes account for most of it: the endpoint is subscribed to a different event than the one you expect, the handler takes longer than 15 seconds to answer, or the endpoint was auto-disabled after a long outage.
Verifying that a webhook came from us
Every message we send is signed, and each endpoint has its own signing secret, separate from your API key. Verification is optional but recommended for endpoints exposed to the public internet. The webhooks reference covers the verification libraries, the signing secret, and the mistakes that cause verification to fail.
Updated about 1 month ago