A reliable blockchain webhook receiver authenticates a delivery, stores it durably and applies the corresponding work through an idempotent process. Network retries are normal conditions to handle. This guide focuses on the receiving endpoint. Use the event and payload guide to choose subscriptions and the replay guide for chain-state recovery.
Preserve the raw request for signature verification
Follow the service’s documented signature and timestamp rules. Where verification uses raw bytes, preserve them before JSON parsing or reserialization. Keep signing secrets out of request logs and compare signatures using the documented algorithm. Authentication establishes the delivery source; it does not establish that the underlying event is finalized or that the business action should be repeated.
Persist the delivery before acknowledging it
Store the authenticated payload and documented delivery identifier in durable storage. Acknowledge according to the provider’s current contract only after the required receipt step succeeds. Keep slow business work outside the HTTP request path where the contract permits it. If storage fails, preserve a retryable failure rather than reporting success and losing the observation.
Deduplicate delivery and business effects separately
Use a durable uniqueness check for the delivery identifier. Several deliveries may refer to one chain event, and separate events may update the same order. Apply business transitions using stable application identifiers and state rules so a repeated worker attempt cannot repeat an irreversible action. A valid signature does not remove this requirement.
Process through a worker with visible failure states
Let the worker record success, retryable failure and unresolved work. Bound retries and route persistent failures to an owned queue. Preserve the original payload, processing error and correlation identifiers for diagnosis. Do not silently discard a delivery because a downstream service is temporarily unavailable.
Handle out-of-order observations
Treat notifications as inputs to the state model rather than commands that always advance it. If two observations conflict, query the relevant documented API or chain evidence before deciding the state. Keep provisional and final states distinct according to the application’s confirmation policy. The replay consumer must be able to revisit recent observations when chain history changes.
Test the receiver contract end to end
Test invalid signatures, repeated deliveries, worker restarts, failed storage, delayed messages and an unavailable downstream dependency. Confirm that every accepted delivery can be found in storage and that repeated processing produces the same intended outcome. Verify exact signature and acknowledgement details in the current service documentation; webhook products can have different contracts.
Frequently Asked Questions
Should the receiver return success before storing the event?
Follow the documented service contract, but ensure an acknowledged delivery is not lost if the process stops. Durable receipt before acknowledgement is a common design for that requirement.
Does signature verification prevent duplicate processing?
No. It authenticates the delivery source under the documented scheme. Delivery deduplication and idempotent business transitions remain application responsibilities.
Can a delivery identifier replace a transaction hash?
They serve different purposes. A delivery identifier tracks notification handling; a chain transaction reference helps verify the observed on-chain activity. Preserve both when provided.