Priority Queues

Assign priority levels to webhooks so that critical webhooks are dequeued and delivered before lower-priority traffic — even under heavy load.

How it works

Every webhook has a priority field ranging from 1 (critical) to 5 (low). The delivery queue processes events in priority order: all priority-1 events are dequeued before priority-2, and so on. Within the same priority level, events are processed in FIFO order.

Priority levels

Priority	Label	Use case
1	Critical	Payment confirmations, security alerts, auth events
2	High	Order updates, inventory changes
3	Normal (default)	General webhooks, notifications
4	Low	Analytics events, non-urgent updates
5	Background	Logging, audit trails, batch syncs

ℹIf no priority is set, the default is 3 (Normal). Existing webhooks are unaffected — they continue to process at normal priority.

Setting priority

On the webhook

Set the default priority for all events received by a webhook via the webhook configuration or the API:

PATCH /api/webhooks/:id

jsonRequest body

{
  "priority": 1
}

Per-event override

Override the webhook's default priority on a per-event basis by including the X-HW-Priority header when sending an event to the ingress URL:

bashcURL example

curl -X POST https://app.hostwebhook.com/api/webhooks/in/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -H "X-HW-Priority: 1" \
  -d '{"event": "payment.completed", "amount": 9900}'

✦The X-HW-Priority header takes precedence over the webhook's configured priority. Use it for events that need urgent processing even on a normally low-priority webhook.

Queue behavior

The BullMQ delivery queue uses priority-aware dequeuing. When the worker picks the next job:

Priority-1 jobs are always picked before priority-2, and so on.
Within the same priority, jobs are picked in the order they were enqueued (FIFO).
Retries inherit the original event's priority level.
A burst of low-priority events does not block high-priority events that arrive later — they jump ahead in the queue.

Example scenario

textQueue state

Queue (front → back):
  [P1] payment.completed   ← processed first
  [P1] auth.mfa_verified   ← processed second
  [P2] order.shipped        ← processed third
  [P3] user.updated         ← processed fourth
  [P5] analytics.pageview   ← processed last

⚠Priority queues do not guarantee strict latency SLAs. They control relative ordering — a priority-1 event is processed before a priority-5 event, but absolute delivery time still depends on queue depth and worker capacity.