How Do You Secure an Inbound Document Webhook?

A supplier portal sends a new insurance certificate to your document platform. The connection times out, so the portal sends it again. Your intake service needs to identify the supplier, select the right vendor and site, check the file, and create one traceable submission despite the retry.

Secure an inbound document webhook as a controlled intake route: verify the sender, bind its permissions to a destination, validate the submission, and make repeated delivery safe. An HTTP success response should have a defined meaning, with a separate status for the document's business acceptance.

Choose the intake route before choosing the controls

A webhook is an HTTP request sent when another system has something to report. In document intake, that might be a form submission, a document payload, or an event that identifies a file to retrieve. Agree which of these the sender actually delivers; a JSON notification does not necessarily contain the PDF itself.

Verify the sender before interpreting the submission

Use HTTPS and the sender's documented verification protocol. For signed deliveries, retain the exact request bytes through the proxy and framework, then verify the signature before trusting parsed fields. Use the provider's supported library and a timing-safe comparison where required. Keep signing secrets in a managed secret store and plan rotation.

Providers differ. GitHub signs the payload with HMAC-SHA256; other providers use different envelopes and signed timestamps. Do not invent a common signature format or assume every sender supplies a verifiable timestamp. An IP allowlist can add a restriction, but should complement message or service authentication.

Authenticate the intended integration as well as the sender. A valid credential for supplier A must not authorise submissions for supplier B. Derive the permitted FormKiQ site, supplier identity, document types, and processing route from trusted configuration. Reject conflicting values in the request instead of allowing them to override that mapping.

Give each control a clear job

Make retries safe across the whole operation

A valid signature does not prevent the same valid request from arriving twice. Use the sender's stable event identifier, scoped to its integration and destination, as a deduplication key. Where the protocol supplies a signed timestamp, enforce a documented tolerance without treating an unsigned timestamp as proof of freshness. GitHub's delivery guidance, for example, identifies a delivery header that remains the same on redelivery.

Claim the event atomically in durable storage before starting side effects. Record the payload digest and operation state. A duplicate with the same content should return or reference its existing receipt; the same key with different content should produce a conflict for investigation. Keep the entry through the sender's retry and operational replay period.

Handle interrupted work too. If document creation succeeds but the worker crashes before recording the result, a retry must reconcile the existing document using a durable correlation reference rather than blindly create another one. Apply the same principle to downstream notifications and approvals. A queue alone does not provide this guarantee: Amazon SQS standard queues can deliver a message more than once.

Separate durable receipt from release into the workflow

1. 1 · Receive

   Verify and record

   Authenticate, bind the destination, enforce admission limits, claim the event, and durably record accepted work before acknowledging it.

2. 2 · Inspect

   Restrict processing

   Check schema and content, run configured scanning, and keep pending submissions away from ordinary users and business actions.

3. 3 · Release

   Apply business rules

   Publish the accepted document into the intended workflow or record a rejection with an accountable owner and receipt status.

Define the response contract for the adapter. A successful acknowledgement can mean “durably received for processing”; it should not imply that a certificate is valid or a supplier is approved. Give the partner a correlation ID and an authorised status or reconciliation channel. Do not acknowledge work that exists only in process memory.

Use file-type allowlists, size and count limits, safe filenames, and restricted storage and access, following OWASP's file-upload guidance. A claimed MIME type or clean malware result does not establish business validity. FormKiQ's selected Anti-Malware / Antivirus module supplies scanning results; configure access and downstream actions around the required scan outcome. Treat a timeout or unavailable result as pending or failed, with a defined recovery path.

If an event points to a remote file, constrain retrieval to the configured source. Apply destination checks to resolved addresses and redirects, and block access to internal services. OWASP's SSRF guidance explains why a supplied URL needs more than a superficial hostname check. Limit retrieval size, duration, and processing cost before invoking OCR or AI.

Work through a supplier certificate retry

In this fictional integration, a supplier portal sends event evt-00421 for a certificate associated with vendor V-0187. The adapter maps that portal to a fixed site and a permitted certificate-intake route.

1. Authenticate and claim

   The adapter verifies the provider's signature and permitted event type, checks the vendor mapping, then claims the scoped event ID and records the payload digest. It acknowledges only after the receipt and processing handoff are durable.

2. Receive the retry

   The first response is lost. The portal resends the event; the adapter authenticates it again and returns the same receipt. A simultaneous worker cannot claim a second operation for that key.

3. Inspect the document

   The worker retrieves the file through the approved source interface, checks its format and limits, and runs the configured scan. The pending file remains restricted. Failed inspection records a rejection or review task without initiating the supplier-renewal workflow.

4. Complete and reconcile

   A successful submission links the receipt to the FormKiQ document ID and verification workflow. Expiry and coverage checks determine the business outcome. Operations can reconcile stuck receipts and retry incomplete steps without duplicating the supplier record.

Test the controls and the recovery path

• Change one signed payload byte, remove credentials, and test the previous and replacement keys during rotation.
• Submit another site's identifier, vendor mapping, approval flag, and an unauthorised processing destination.
• Send concurrent duplicates, reuse an event ID with changed content, and retry after losing the success response.
• Interrupt processing immediately after document creation and confirm recovery links the existing document.
• Test oversized and misleading files, controlled malware test samples, scan failure, and remote-file redirect restrictions.
• Confirm pending content cannot appear in ordinary search, previews, downloads, sharing, or business actions before release.
• Reconcile aged receipts and permanent failures; verify that logs omit credentials and unnecessary sensitive payloads.

Record the sender, integration, event ID, trusted destination, receipt time, payload digest, validation outcome, document IDs, and processing state. Assign an owner to stuck and rejected submissions. Protect receipt and diagnostic access so one partner cannot inspect another's documents or outcomes.

Make intake trustworthy before automating the next step

Start with one sender, one document type, and one destination. Prove that the integration identifies the sender, survives repeated delivery, restricts pending content, and explains each outcome. Then connect accepted documents to the business workflow with the same correlation trail.

Technical guidance reviewed: November 12, 2026, against the linked FormKiQ, GitHub, AWS, and OWASP documentation. The receipt states and event IDs above illustrate the integration design.