Marketplace Webhook Receiver Guide: Signatures and Retries

A marketplace alert webhook is valuable only if the receiver can accept it safely and exactly once at the business-action layer. Network delivery itself is not exactly once. Timeouts, connection failures, retries, and manual redelivery mean the same event can reach your endpoint more than once.

Classifindr uses signed CloudEvents JSON and Standard Webhooks headers. The receiver contract is intentionally small: authenticate the raw request, protect against replay, accept durably, respond quickly, and make downstream processing idempotent.

The safe acceptance sequence

Process an incoming request in this order:

1. Require POST over HTTPS.
2. Read and retain the exact raw UTF-8 body within your own request-size limit.
3. Read Webhook-Id, Webhook-Timestamp, and Webhook-Signature.
4. Reject a timestamp outside the allowed five-minute window.
5. Verify at least one v1 signature using the endpoint secret and raw body.
6. Insert Webhook-Id into a durable table with a unique constraint.
7. Store or enqueue only the bounded work your application needs.
8. Return a 2xx response.
9. Perform slower actions outside the request path.

Do not parse and serialize the body again before verification. Even semantically identical JSON can have different whitespace, key order, or escaping, which changes the signed bytes.

Understand the signed message

The signature input combines the webhook ID, timestamp, and exact request body. The published Node.js verification example and Python verification example implement the current format without requiring you to infer it from a sample payload.

Keep the whsec_ secret in server-side secret storage. It must not be included in browser code, mobile code, public repositories, analytics, exception reports, or request logs. When a secret is rotated, Classifindr can include signatures for the overlapping keys for 24 hours. A receiver should accept the delivery when any valid v1 signature matches.

Make duplicate handling a database rule

An in-memory set is not enough. It disappears on restart and does not coordinate two receiver instances. Use a durable table keyed by Webhook-Id and let a unique constraint settle races.

A practical record can contain:

• webhook_id as the unique key
• event type and schema version
• received timestamp
• processing state
• a safe internal job identifier
• completion or bounded failure status

When the insert conflicts, return a 2xx response without repeating the business action. A manual redelivery intentionally reuses the original event ID and body, so the same rule protects both automatic retries and operator-triggered redelivery.

Separate acceptance from processing

The receiver should finish authentication and durable acceptance before calling a slow database enrichment job, messaging platform, spreadsheet API, or inventory service. Queue that work after the event is stored.

This split gives you two independent retry decisions:

• Classifindr retries delivery until your receiver safely accepts the event.
• Your application retries its own downstream job without asking Classifindr to resend the request.

If your job fails after the webhook already received a 2xx response, retry the job from your own queue. Do not remove the deduplication record and hope a repeated webhook reconstructs application state.

Validate the CloudEvent before routing it

After signature verification, parse the JSON and require the event type and schema version your application supports. V1 alert events are alert.listing.matched.v1 and alert.listing.price_decreased.v1. Ignore or quarantine an unsupported type instead of treating every JSON object as a new listing.

Listing titles and descriptions are untrusted public marketplace text. Render them as text, not HTML. Do not turn a listing URL, thumbnail URL, description, or seller wording into a command, SQL fragment, template, or unvalidated outbound request.

Use the public alert schema in tests so a new optional field does not break a receiver that only needs the listing ID, title, price, source URL, and search context.

Handle order without making order assumptions

Webhook deliveries are unordered. A price-decrease event can be delayed while another event reaches your system first. Model each event as a fact identified by its ID and type, not as the assumed next step in a sequence.

If a dashboard needs current listing state, compare timestamps and state transitions inside that application. If it only needs a review queue, append the accepted event and let the buyer open the source listing for current availability and price.

Test failure paths before adding more searches

Use the recorded test event from the desktop web portal to check:

• valid signature acceptance
• invalid signature rejection
• stale timestamp rejection
• duplicate ID handling
• quick 2xx acknowledgement
• safe handling of unsupported event types
• queue or database recovery after a downstream failure

Then assign one low-volume Classifindr search and inspect a real listing-match delivery. Delivery history shows bounded payload snapshots, attempts, and safe failure reasons for 30 days. Correct the receiver before using manual redelivery.

Choose the right endpoint boundary

Use a dedicated path such as /webhooks/classifindr rather than a generic endpoint that accepts unrelated event formats. Apply a small body limit, accept only the expected content type, keep request logs free of headers and bodies, and rate-limit obvious abuse without breaking legitimate retries.

If an automation platform sits in front of your application, confirm it can give your verification step the original body and signature headers. If it changes the request before verification, terminate the signed webhook at a receiver you control and forward only the verified, minimal data needed by the downstream workflow.

The first success criterion is not an elaborate automation. It is a receiver that accepts a signed test event, rejects a forged one, records an event ID once, and returns quickly. Build the buying workflow on top of that dependable boundary.