Appearance

Webhooks ​

The most flexible outbound integration. Fire an HTTP POST to your endpoint when documents reach configurable states. Recognito recommends HTTPS. Real-time, configurable per project, with built-in retry on failure.

This page is the operational view — when webhooks fire, how to configure them, and what to expect. For the developer-side reference (exact payload shape, headers, code samples), see the API webhook guide.

What a webhook is ​

A webhook is an HTTP POST that Recognito sends to your endpoint when something happens. Recognito recommends an HTTPS URL. The payload contains the document's data (shaped by your Custom Response Schema, if configured).

You configure:

  • The URL to POST to.
  • The trigger events — Document Analysed, Document Validated, Document Approved (any combination).
  • Whether to include the source PDF alongside the data.

Once configured, every matching event fires a POST.

Where to configure ​

Settings → Integrations → Webhook.

For the webhook:

  • Endpoint URL — where to POST. Recognito recommends HTTPS.
  • Trigger events — pick one or more.
  • Include files — whether the source PDF rides along (multipart form data).

Save the webhook. Future events on the configured triggers will fire to the URL.

Trigger events ​

Three events you can subscribe to:

EventFires when
Document AnalysedExtraction and Initial_Workflow complete. Document Status flips to Done.
Document ValidatedAn assignee marks the document Validated.
Document ApprovedAll required approvers have signed off. Approval Status is Approved.

Most customers configure Document Approved only — fire after final sign-off, push to the ERP, done. Configuring multiple events is useful for:

  • Real-time tracking dashboards — fire on all three to track every state change.
  • Pre-approval staging — fire on Document Analysed to stage data in a sandbox, then on Approved to promote.

Reference for the Document Validated trigger

The public webhook documentation has historically described the Document Analysed and Document Approved triggers. Document Validated is also supported but may need to be confirmed in your specific deployment. If the Validated trigger isn't behaving as expected in your project, contact Recognito support.

Payload shape ​

The payload is multipart form data containing:

  • The structured document JSON in a form field. Shape governed by your Custom Response Schema (Settings → Developers).
  • The source file (PDF or image) in another form field, if "include files" is on.

For the full payload reference, headers, and code samples for receiving the webhook, see the API webhook guide. It covers the exact JSON structure, file handling, and verification recommendations.

Retry behavior ​

If your endpoint doesn't respond with a 2xx within 30 seconds (or responds with a non-2xx), Recognito retries:

  • First retry: 1 minute after the initial attempt.
  • Second retry: 5 minutes after the first retry.
  • Third retry: 10 minutes after the second retry.
  • After three failed attempts: the webhook is marked failed.

There's no built-in "replay failed deliveries" affordance today. Once marked failed, the delivery doesn't re-fire automatically. If you need replay, the path is to capture the document via API and process it yourself.

Plan your endpoint for the retry behavior:

  • Make your endpoint idempotent. Receiving the same payload twice (because of a retry on transient failure) should produce the same end state.
  • Acknowledge fast. Respond with 2xx within the 30-second window. Defer slow processing to a background worker.
  • Monitor failed webhooks. Set up alerting if a webhook starts marking deliveries failed — you may have an outage or a bug.

Verification ​

There's no HMAC signing on Recognito webhooks today. The public docs recommend:

  • Validate the source domain (the IP / hostname the POST comes from).
  • Use HTTPS for the endpoint URL.
  • Restrict access at the network layer if your endpoint is sensitive.

For high-security integrations, validate that the JSON payload contains an expected secret, or restrict access at the network layer.

No HMAC signing today

If your security requirements demand cryptographic verification of webhook authenticity, raise it with Recognito support. The current verification model is domain + HTTPS only; HMAC signing may be on the roadmap but isn't shipped today.

Failed delivery handling ​

When a webhook fails its three retries, there's no in-product view of the failed delivery. You'll typically discover it via:

  • Your receiver's logs — if you're getting fewer webhooks than expected.
  • Active monitoring — set up alerts on your receiver for missing deliveries.

For documents where the webhook failed, the data is still in Recognito. You can:

  • Re-export manually via clipboard or print.
  • Pull via API using the GET endpoints.
  • Wait for the next state change if more trigger events will fire.

When to use a webhook vs alternatives ​

ScenarioUse…
Single push to one systemWebhook
Push to multiple systems / orchestrationMake.com or n8n
Custom transformation before deliveryMake.com / n8n, or webhook to a transformation service
Pull-style integrationAPI + scheduled pull from your side
Standard ERP integrationCheck the ERP connectors first

Webhooks excel at "Recognito has new data, push it to one place." They're the fastest path to a working integration when you have a custom downstream system and a developer to write the receiver.

What's next ​