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.
- Find the Webhooks card 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.
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
Each stage of processing emits a success event and an error event. The two most integrations need:
| 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. |
There are equivalent events for classification, splitting, merging, schema creation and visual review, plus a .error variant of each. The full list is in the webhooks reference.
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.
On a very large document the parsed text or the extracted data can exceed the size we can deliver in a single message. When that happens we send the event with a textTooBig or dataTooBig flag instead of the oversized field, and your handler fetches the full result from the API using the id in the payload.
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.
Common causes worth checking first: 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 2 hours ago