Webhooks

Have SimplyParse push each result to your server as soon as a document is processed.

A webhook is an HTTP request SimplyParse sends to your endpoint whenever a document finishes processing. You don't need to poll, and results reach your system within moments.

When webhooks are sent

A webhook fires once per entry when processing finishes for a document that was:

submitted through the async endpoint, or
uploaded in the dashboard.

Documents processed through the sync endpoint don't trigger webhooks, because the response already contains the result.

Two settings filter what is sent:

Environment. A webhook only receives documents whose environment matches its own (both default to default). Send environment=staging from staging and point a staging webhook at your staging server.
Block Invalid Documents. If this parser setting is on, entries that fail validation are not sent. They stay in the dashboard for review.

Set up a webhook

Create an endpoint on your server

It must accept a POST with a JSON body over HTTPS, and answer quickly with any 2xx status. A complete, signature-checking receiver is in Receive results with a webhook.

Add the webhook to your parser

Open the parser, go to Integrations, and add a webhook:

Setting	What to enter
Name	Something you'll recognise, such as `ERP production`.
Environment	The `environment` value your API calls send (`default` if you don't send one).
URL	Your endpoint, for example `https://api.example.com/hooks/simplyparse`.
Method	`POST` (recommended).
Headers	Optional extra headers sent with every delivery. Use them for a shared secret, such as `X-Webhook-Secret: <random value>`.

Save the webhook.

Send a test document

Submit a document with the async endpoint (using the same environment) or upload one in the dashboard, and watch your endpoint receive it.

The request

POST /hooks/simplyparse HTTP/1.1
Content-Type: application/json
X-SimplyParse-Signature: 9c1185a5c5e9fc54612808977ee8f548b2258d31f3ae5a9e8e1a3c8a7d4e2b10
X-Webhook-Secret: your-configured-header

{
  "status": "success",
  "code": "document_processed",
  "message": "Document processed successfully",
  "data": {
    "document_id": "3c59dc04-8a4e-4d6b-9f3e-7a1f0e2b5c66",
    "entry_id": "8f14e45f-ceea-467f-a8e6-3c1d2f0b9a51",
    "status": "completed",
    "is_valid": true,
    "parsed_data": {
      "invoice_number": "INV-20418",
      "vendor_name": "Northwind Supplies",
      "total_amount": 48250
    },
    "validation_errors": []
  }
}

Field	Description
`data.document_id`	The document, as returned by the async endpoint. Match it to your stored submission.
`data.entry_id`	The entry. Use it as your idempotency key and to correct values.
`data.status`	Usually `completed`, or `duplicate` if a unique field matched an existing entry.
`data.is_valid`, `data.validation_errors`	Validation results, as described in Responses.
`data.parsed_data`	The extracted values, or the output of your data mapping if one is configured.

A document with several entries produces several requests that share a document_id.

Responding and redelivery

Return 2xx quickly. Store the payload and do slow work, such as calling your ERP, in a background job. Any non-2xx status, timeout or connection error is recorded as a failed delivery.
Failed deliveries aren't retried automatically. Redeliver them from the dashboard: in the parser's View data tab, open a document's actions menu and choose Integrations → Redeliver Failed (or Redeliver All). Run a polling safety net if you can't afford to miss one.
Expect duplicates. A redelivery sends the same entry_id again. Make your handler idempotent: upsert by entry_id instead of inserting.

Secure your endpoint

Anyone who knows your URL can send it requests, so check that each one really came from SimplyParse:

Shared-secret header. Add a header with a long random value to the webhook and reject requests without it. It's simple and strong.
Signature. Verify X-SimplyParse-Signature to confirm the body wasn't altered. See Verify signatures.

Use HTTPS so the payload and your secret header are encrypted in transit.

If the receiving system expects different key names or structure, such as an ERP import format, add a data mapping to the webhook. SimplyParse then transforms parsed_data before sending, so you don't need glue code in between.