Troubleshooting

Webhooks are not being delivered

1. Check the buffer

1. Open Buffers in the dashboard
2. Make sure the buffer is enabled. It may have been auto-paused after repeated failures
3. Check that the delivery URL is correct and reachable from the internet (not localhost)
4. Use Test on the buffer to send a sample payload straight to the destination and see its response

2. Check the DLQ

Open DLQ and look for entries for the buffer. The last error tells you what happened:

• HTTP 5xx: your endpoint failed
• HTTP 4xx: your endpoint rejected the batch (wrong URL, missing auth header, parsing error); not retried
• connect ECONNREFUSED …: nothing is listening at the destination
• Timeout: your endpoint took more than 10 seconds

3. Test your endpoint directly

curl -i -X POST https://your-app.example.com/webhooks/batch \
  -H "Content-Type: application/json" \
  -d '{"webbu": {"groupKey": "test", "segment": 0}, "window": {"itemsCount": 1}, "items": [{"messageId": "test-1", "receivedAt": 0, "payload": {"test": true}}]}'

It should answer 2xx within 10 seconds.

4. Check that ingest works

curl -i -X POST https://webbu.dev/api/v1/ingest/YOUR_PROJECT_ID/YOUR_BUFFER_ID \
  -H "Content-Type: application/json" \
  -d '{"test": true, "customerId": "test"}'

Expect 202. Use a body that contains your group key field. Then look at Total Requests on the dashboard.

Ingest returns 400

Ingest returns 401, 403 or 404

• 401 Missing signature header / Invalid signature: source verification is enabled; see Security
• 401 Unauthorized: you sent an X-API-Key that is invalid or revoked. Ingest works without a key
• 403 API key does not have access to this buffer: the key is from another account or not scoped to this project
• 404 Buffer not found: wrong buffer ID, or the buffer was deleted

Ingest returns 429

Your credit balance is too low:

{"error": "Insufficient credits", "credits": 3, "required": 5, "message": "Please add more credits to continue receiving webhooks"}

• Wait for the monthly reset, upgrade your plan or buy a credit pack (packs need an active subscription)
• Check payload sizes: each started KB uses 1 credit

Deliveries arrive later than expected

The idle timeout keeps resetting. With steady traffic, idleTimeoutMs never expires. Set maxWaitFromFirstMs to bound the wait.

Low traffic and a high maxItems. The group waits for the idle timeout or max wait. Lower them if you need faster delivery.

Retries. A failing endpoint delays the batch by the backoff between attempts.

Duplicate deliveries

Delivery is at least once: if your endpoint answers after 10 seconds, the batch is sent again even if you processed it.

• Answer quickly and process asynchronously
• Deduplicate by items[].messageId
• Send stable message IDs at ingest (messageId in the body or X-Idempotency-Key) so resends from your sender are deduplicated too

Management API errors