Status and scope
This is general engineering guidance for evaluating a future integration. The Anti Sandbox V4 webhook contract is release gated. No header names, signature algorithms, payload fields or timing tolerances are specified here. Obtain the contract for the deployed release before implementing a receiver.
Inbound inboxes and outbound events are different
An inbound webhook inbox accepts messages into a conversation. An outbound event webhook notifies your service about changes. Each direction needs its own authorization, validation and retry rules. Do not assume credentials or schemas are interchangeable.
Authenticate the original request
Preserve the raw request bytes before parsing JSON. Verify the signature using the documented contract and the correct secret for that connection. If the contract includes a timestamp, validate its authenticity and freshness using its documented tolerance. Use the documented constant-time comparison procedure. Never log a secret or accept a failed verification.
Prevent replay and duplicate processing
Authentication alone does not prevent a valid event arriving more than once. Use the contract’s documented event identity and connection scope to record processing state durably. Treat a repeated event as the same work, not permission to send a second customer reply. Coordinate deduplication with recovery after a crash.
Accept durably, then process
Validate and persist an accepted event before acknowledging it according to the provider contract. Keep slow agent work outside the request path. Track accepted, processing, failed and completed work. Retry only transient failures with bounded backoff; malformed or unauthorized events need investigation rather than an endless retry loop.
Preserve human ownership and delivery evidence
A retry must not revive an agent response after a human takes over. Recheck conversation ownership before sending. Keep correlation records from the accepted event through the reply attempt to the provider’s delivery outcome, with sensitive content minimized. Test a duplicate, a stale signed request, an invalid signature, a crash after acceptance and a human takeover before launch.