Pro and above · Compare plans and subscribe
Process webhook retries without duplicate effects
Verify MadeOnSol webhook signatures and acknowledge deliveries after durable storage so retries do not duplicate alerts.
Integration choice
Choose a unique key for each effect. Write the event and its deduplication key atomically before returning success. Make downstream work retryable if the receiver restarts after acknowledgement.
Implementation steps
- Register your HTTPS endpoint and select an event in the webhook settings. Save the signing secret on your server.
- Capture the original body bytes before JSON middleware runs. Pass them, the timestamp header, the signature header and your literal signing secret to the verifier below. Its five-minute freshness window is a receiver policy.
- After verification, validate the payload and persist it to a durable queue before acknowledging. Where a delivery ID is supplied, store it with the queued event under a unique constraint. For other events, choose a stable event-specific identity before performing repeat-sensitive work.
- Send a sample with POST /api/v1/webhooks/test using your API key and a JSON body containing the numeric webhook_id. Check success and status_code in the response. In your own receiver tests, alter one body byte and submit the same valid delivery twice. Expect rejection for the altered body and one application effect for the repeated delivery.
Code examples
Node.js signature verifier
import crypto from "node:crypto";
// rawBody: the exact request bytes (never re-serialized JSON)
// secret: the webhook secret exactly as the API returned it (do not hex-decode)
function verifyMadeOnSol(rawBody, timestamp, signature, secret) {
// X-MadeOnSol-Timestamp: unix milliseconds, fresh on every retry
if (typeof timestamp !== "string" || !/^\d{1,16}$/.test(timestamp)) return false;
// Replay window: your choice, the server does not enforce one
if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60_000) return false;
// X-MadeOnSol-Signature: 64 hex characters, bare (no algorithm prefix)
if (typeof signature !== "string" || !/^[0-9a-f]{64}$/i.test(signature)) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest();
// Both sides are exactly 32 bytes here, so this compares in constant time and cannot throw
return crypto.timingSafeEqual(expected, Buffer.from(signature, "hex"));
}Verify your integration
Deliver one signed event twice and stop the worker after the first queue write. On restart, the event should still be available and the application should produce one alert. Altering the signed bytes should prevent a queue write.
