Delivery and retries

Method: POST
With a JSON body.
Timeout: 20 seconds
A request that takes longer counts as failed.
Success: Any 2xx status
Other statuses, including 3xx redirects, are retried.
Retry delay: 30 seconds or more
Increases after each attempt, with random jitter.
Retry limit: 60 hours
After 60 hours from the first attempt, the event is dropped.
Concurrency: Limited per host
Bigblue limits how many requests it sends to one host at once.

Bigblue records the response status and the number of retries for each request, so support can see what your endpoint returned.

Events are dropped after 60 hours

There is no way to replay old events. If your endpoint is down for more than 60 hours, sync your data with the API. See Nightly sync.

Building your endpoint

Respond first, process later

Check the signature, put the event in a queue and return 200. Do slow work, such as database writes or API calls, after responding.

Handle duplicates

The same event can arrive more than once.

Inventory rows contain current values. Overwrite your stored values. Don't add or subtract.
Order statuses only move forward. Ignore a status older than the one you have.

Don't rely on order

Events can arrive out of order, because each one is retried separately. Compare update_time to skip old events:

if (stored.updateTime && payload.update_time < stored.updateTime) return;

export async function POST(req: Request) {
  const raw = await req.text();

  if (!verify(raw, req.headers.get('x-bigblue-hmac-sha256'))) {
    return new Response('invalid signature', { status: 401 });
  }

  const type = req.headers.get('x-bigblue-event-type');
  const body = JSON.parse(raw);

  if (type === 'URL_VERIFICATION') {
    return Response.json({ challenge: body.challenge });
  }

  try {
    await queue.push({ type, body });
  } catch {
    // The event wasn't saved, so ask Bigblue to retry.
    return new Response('queue unavailable', { status: 503 });
  }

  return new Response(null, { status: 200 });
}

Return an error only when you couldn't save the event, so that Bigblue retries it.

Several endpoints

You can register several endpoints for one event type, for example production and staging. Each one has its own retries. They all use the same shared secret.

Nightly sync

Run these jobs to catch events your endpoint missed:

When	Job
Continuously	Webhooks update your data within seconds.
Nightly	Page through `ListInventories` with `page_size: 1000` and overwrite your stock.
Nightly	Page through `ListOrders` for the last 48 hours and update statuses.

Building your endpoint

Respond first, process later

Handle duplicates

Don't rely on order

Return 401 for invalid signatures

Accept unknown event types

Example

Several endpoints

Nightly sync

On this page