Secure Outbound Document Webhooks

Validate destinations, authenticate deliveries, and recover from uncertain outcomes

Published

Secure Outbound Document Webhooks. Three flat teal panels show an approved destination, a signed message, and delivery recovery, labelled Validate, Deliver, and Recover, above the official FormKiQ logo.

An outbound document webhook needs three agreements: where the event may go, how the recipient verifies it, and how both systems recover when delivery is uncertain. Keep one stable business event across retries, record each network attempt separately, and define exactly what an acknowledgement means.

Suppose procurement approves a replacement supplier certificate. The receiving system accepts the notification, but its response is lost. Sending it again may be necessary; approving the certificate or changing the supplier's status again may be harmful. This guide follows the sending side of that handoff. For admitting documents from external senders, see secure inbound document webhooks.

Approve the destination and the data it receives

A callback registration should identify its owner, tenant or site, permitted event types, payload contract, and recipient. Limit who may change it. Prefer the document identifier, selected version, and required business references to sending an entire file. Define an authenticated retrieval path when the recipient needs content. Review the actual outgoing payload; internal event data may contain metadata or access-bearing links unsuitable for a partner.

Require HTTPS and restrict hosts and ports to the intended recipients. For public callbacks, block loopback, link-local, private, cloud-metadata, and other non-public IPv4 and IPv6 destinations. A deliberately private integration needs its own approved network path. Disable redirects so a permitted URL cannot redirect the request into another network. These controls address the callback risk described in OWASP's SSRF prevention guidance.

Validate the connected address; a separate DNS lookup inside the HTTP client leaves a rebinding gap. Use a connect-time check or a validated address with the original hostname for TLS verification, SNI, and Host. A controlled egress proxy can enforce this policy. Isolate workers from internal services. See OWASP's publisher-side webhook controls.

Separate the event, attempt, and outcome

  1. 1 · Validate

    Approve the handoff

    Select the recipient, event, document version, and permitted payload.

  2. 2 · Deliver

    Authenticate each transmission

    Keep the business event stable while recording separate network attempts.

  3. 3 · Recover

    Reconcile the result

    Resolve uncertain receipts and exhausted retries before repeating business work.

A retry follows an unsuccessful or uncertain transmission. An operator replay deliberately resubmits retained work after review. Both need a link to the original business occurrence. A new attempt identifier helps support staff trace the request; it must not turn a duplicate into a new business event.

Proposed integration delivery record. These are application fields, with their own storage and lifecycle.
RecordWhat it establishes
Business eventStable event ID, type, occurrence time, document/version, and business reference. Reuse it for retries of that occurrence.
Recipient configurationApproved destination, site/tenant scope, subscription, and configuration version used for disclosure.
Network attemptUnique operational attempt ID, timing, response or timeout, and automatic-retry or authorised-replay relationship.
Payload and authenticationContract version, protected payload reference or fingerprint, signing-key version, and authenticated transmission time. Exclude secret values.
Receipt and business resultWhether the recipient durably accepted the event, completed the intended work, rejected it, or still needs reconciliation.

Use a defined signing protocol

Agree the protocol and maintained verification library with the recipient. For example, Standard Webhooks authenticates the message ID, transmission timestamp, and raw body together. Its message ID remains stable across retries; the timestamp and signature are refreshed. A separate attempt ID can stay in the delivery log. Sign the final wire bytes after payload transformations, and verify before parsing changes those bytes. Do not assume a transport's connection credentials also provide this message-signing protocol.

For a shared-secret scheme, use a separate secret per destination and managed secret storage. During planned rotation, coordinate a bounded overlap and revoke the old key afterward. Suspected compromise calls for immediate revocation and replacement. Redact secrets, authorization/signature headers, and sensitive bodies from logs; retain operational identifiers and outcomes. These practices follow the OWASP secret-management guidance.

Agree durable duplicate handling with the receiver

A freshness check rejects captured old transmissions. Durable duplicate handling answers a different question: has this business occurrence already been accepted or applied? Agree the duplicate key's publisher, recipient, and business-operation scope. Retain its processing record across the supported retry and replay period; route older recovery requests to reconciliation when that record has expired.

Design the receiver's unique claim and durable work admission together, using a local transaction where possible. A claim followed by a crash before queueing must not lose the work. A side effect followed by a crash before recording completion must not repeat it. For an external side effect, use that system's idempotency key or a supported lookup and reconciliation process. A repeated event with a different payload needs investigation.

Define a successful HTTP response as durable acceptance or completed processing, according to the contract. A queued receipt leaves business completion pending. Also agree how older events affect newer state. Stripe's webhook documentation, for example, explicitly warns that deliveries can be duplicated and arrive out of order. In your integration, use a guaranteed source sequence if available, or reconcile against authorised current state; a timestamp by itself is insufficient.

Bound retries and make recovery visible

Set a maximum event age, total attempt budget, destination rate limit, and backoff with jitter. Coordinate worker, queue, and transport retries so they do not multiply unexpectedly. Classify responses using the chosen transport's rules and the receiver contract, with alerts for persistent authentication or validation failures. The document action retry guide covers action-level recovery and uncertain side effects.

For EventBridge API destinations, the client execution timeout is five seconds. AWS retries timeouts and selected status codes, including 401, 407, 409, 429, and 5xx. Configure a dead-letter queue for exhausted deliveries; without one, exhausted events are dropped. If a receiver queues work promptly, monitor its later processing failures separately.

Before replay, recheck the recipient's current permission, subscription, payload sensitivity, and whether the old event is still actionable. Record the operator and reason. Preserve the original business identity even if the transport creates a new envelope ID. A changed recipient or broader payload requires an explicit new disclosure decision; do not silently send old document data to a replacement URL.

Work through a lost acknowledgement

This fictional integration notifies procurement that certificate DOC-00091, version 7, was approved. Its delivery records are application design choices, not literal FormKiQ response fields.

  1. Create the event. EVT-00041 identifies this approval and its supplier reference. The integration selects the approved recipient and minimal payload; the notification does not itself authorise a separate supplier-status change.
  2. Lose the response. Attempt ATT-00001 reaches the receiver, which verifies it and atomically records the event with durable work admission. Its acknowledgement is lost. The sender records an uncertain receipt.
  3. Retry during the outage. ATT-00002 carries the same event identity with fresh authentication. The receiver is now unavailable; retries reach the configured limit and unresolved delivery enters the recovery queue.
  4. Replay after review. An authorised operator records RPL-00003 after checking that the recipient is still permitted and version 7 is still relevant. The recovered receiver finds EVT-00041's durable record and returns its accepted status without adding duplicate work.
  5. Close the right result. The sender records the receipt. Separately, the integration confirms the queued business work's outcome or leaves it pending for follow-up. If a newer certificate superseded version 7, the recovery decision records that instead of restoring old state.

Test the handoff before enabling it

  • Attempt a public-to-private DNS change and a redirect; confirm delivery cannot reach a prohibited address.
  • Reject a changed body, stale authentication, and revoked key; exercise planned key rotation.
  • Send concurrent duplicates and crash around durable admission and completion; reconcile one intended business outcome.
  • Deliver an older event after a newer version and verify the agreed state-reconciliation policy.
  • Exhaust all retry layers and confirm an alert, retained recovery record, and accountable owner.
  • Replay after recipient access changes or duplicate-record expiry; require a reviewed decision.
  • Trace accepted-but-pending work without exposing secrets or document contents in logs.

Make the business outcome traceable

A secure outbound handoff has an approved recipient, a verifiable message, bounded recovery, and a clear account of the receiving system's result. Keep those agreements explicit so an uncertain HTTP response can be resolved without repeating an approval, disclosing data to the wrong party, or overwriting newer business state.

      Start with FormKiQ Core

      The open-source foundation — API-first, deployable into your own AWS account, and free to use. Right for architecture validation and early implementation.

      Get Started Free

      Deploy FormKiQ Essentials or Advanced

      Production-ready editions for departments and complex workflows. Start with a Proof-of-Value deployment or go straight to production.

      Explore Options

      Plan an Enterprise Rollout

      For governance-heavy environments with residency, sovereignty, assurance, and multi-jurisdiction requirements. Talk to us about the right deployment model.

      Book a Call