Published

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.
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.
Select the recipient, event, document version, and permitted payload.
Keep the business event stable while recording separate network attempts.
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.
| Record | What it establishes |
|---|---|
| Business event | Stable event ID, type, occurrence time, document/version, and business reference. Reuse it for retries of that occurrence. |
| Recipient configuration | Approved destination, site/tenant scope, subscription, and configuration version used for disclosure. |
| Network attempt | Unique operational attempt ID, timing, response or timeout, and automatic-retry or authorised-replay relationship. |
| Payload and authentication | Contract version, protected payload reference or fingerprint, signing-key version, and authenticated transmission time. Exclude secret values. |
| Receipt and business result | Whether the recipient durably accepted the event, completed the intended work, rejected it, or still needs reconciliation. |
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.
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.
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.
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.
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.
The open-source foundation — API-first, deployable into your own AWS account, and free to use. Right for architecture validation and early implementation.
Production-ready editions for departments and complex workflows. Start with a Proof-of-Value deployment or go straight to production.
For governance-heavy environments with residency, sovereignty, assurance, and multi-jurisdiction requirements. Talk to us about the right deployment model.