Queue

Provenance uses a database-backed queue for reliable notification delivery.

How it works

1. When an interaction matches a subscription, a notification is enqueued automatically via database trigger
2. A cron job (or manual call) processes pending notifications in batches
3. Failed notifications retry with exponential backoff (max 3 attempts)
4. All attempts are logged in the audit trail

Processing the queue

# Process pending notifications
POST /api/queue/process?batchSize=10

Set up a cron job to process automatically:

# Every minute
* * * * * curl -X POST https://provenance.onrender.com/api/queue/process?batchSize=10 -H "x-api-key: your-api-key"

Monitoring

# Queue statistics
GET /api/queue/stats

Returns counts of pending, processing, completed, and failed notifications.

Listing queue items

# List queue items with optional status filter
GET /api/queue?status=pending&limit=50&offset=0

Retrying failed notifications

POST /api/queue/:queueId/retry

Resets a failed notification back to pending for reprocessing.

Deleting queue items

DELETE /api/queue/:queueId

Purging old items

Remove completed or failed items in bulk:

POST /api/queue/purge
{
  "status": "completed",
  "olderThan": "2024-01-01T00:00:00Z"
}

Retry logic

After 3 failed attempts, the notification is marked as permanently failed and logged in the audit trail.

Audit trail

Every notification attempt is recorded:

GET /api/audits

Each audit record includes the adapter response, status code, and any error messages.

Notification interactions

In addition to the audit trail, every notification delivery creates a provenance interaction with the same uowId as the original event. This makes the full lifecycle — from the triggering event through notification delivery — visible in traces and activity search.

See System Interactions for the complete payload reference.