BigCommerce blocklists below 90% success: keep Sume callbacks quick

Keep both ends of a BigCommerce-to-Sume pipeline fast: acknowledge every webhook with a 2xx immediately and do the work afterwards. BigCommerce stops calling a domain for three minutes once fewer than 90% of its callbacks succeed in a two-minute window, and Sume gives your endpoint only 10 seconds per delivery attempt before it counts as failed and retries.

This post compares the two documented behaviours and gives one rule for the handler that sits between them. The reasoning that goes beyond the docs is labeled as such.

What BigCommerce documents

The BigCommerce webhooks page describes a success-ratio guard on the destination, plus an instruction on how fast to answer.

What Sume documents for its own callbacks

Sume sends terminal job events (job.completed, job.failed, job.canceled) to a public HTTPS webhook_url. Your endpoint is on the clock the same way.

How the two interact (reasoning, not a vendor claim)

BigCommerce's guard counts BigCommerce callbacks only, and BigCommerce says blocklisting applies to the specific client_id, not the whole domain. The risk appears when one domain or one worker pool serves both BigCommerce and Sume callbacks. If a Sume callback handler renders, uploads or calls other APIs before it answers, it occupies the same workers that must answer BigCommerce quickly, and a slow worker pool fails both.

A worked illustration: if 100 BigCommerce callbacks arrive in a two-minute window, 11 failures leave 89 successes, which is 89% and below the threshold. 10 failures would sit exactly at 90%, which the page does not describe as below. Sume's retries make this worse, because one slow job callback can spend up to 10 attempts, each tying up a worker for as long as 10 seconds.

A handler that stays out of trouble

• Verify the Sume signature first (HMAC SHA-256 over timestamp.raw_body, 300 second replay window), store the event durably, return 2xx.
• Do rendering, uploads and downstream calls from a queue, not from the request.
• Treat job_id as the idempotency key, because retries and redeliveries carry the same job.
• Give BigCommerce and Sume separate paths, ideally separate worker pools, so one slow tenant cannot sink the other's success ratio.
• Keep polling GET /v1/jobs/{id}/status as a backup. Sume says delivery is an optimisation, never the only recovery path.

If your endpoint was down

After ten refused attempts the delivery has failed but the job has still reached its real terminal state. Call the redeliver endpoint for each job you missed, or read results with the job status and result endpoints. Read the Sume webhooks docs for the signature scheme before you add the handler.