Internal Architecture

We believe in transparency. Here’s how Seamlr processes integration events internally.

Queue System (PGMQ)

Seamlr uses PostgreSQL Message Queue (PGMQ) for reliable event processing:

• At-least-once delivery: Messages are guaranteed to be processed
• Visibility timeout: Messages become invisible during processing
• Automatic retry: Failed messages return to queue after timeout
• Durability: Messages persist in PostgreSQL

Note

PGMQ provides database-level durability, meaning your webhook events won’t be lost even during system failures.

Retry Logic

Attempt	Action
1-4	Process message, retry on failure
5+	Move to Dead Letter Queue (DLQ)

Messages in the DLQ require manual investigation and are not automatically retried.

Processing Times (SLAs)

Operation	Typical Time
Webhook acknowledgment	< 500ms
Shift processing	< 30 seconds
Candidate sync	< 10 seconds
DLQ escalation	After 4 failed attempts

Error Handling

HTTP Status Codes

HTTP Status	Meaning
200	Webhook received and queued
400	Invalid payload schema
500	Internal error (will not retry automatically)

Transient vs Permanent Failures

• Transient failures (5xx from provider API): Trigger automatic retries
• Permanent failures (4xx from provider API): Logged, may require manual resolution

Caution

If your API returns 4xx errors, Seamlr will not automatically retry. Ensure your API handles temporary issues gracefully.

Echo Webhook Prevention

When Seamlr updates or deletes a shift in the provider system, the provider typically sends a webhook back to Seamlr. To prevent infinite loops:

1. Before calling provider API: Seamlr records a “pending operation”
2. Webhook arrives: Seamlr checks for matching pending operation
3. If match found: Skip processing (this is our own change echoing back)
4. Pending operations expire: After 5 minutes, records are automatically cleaned up

This ensures Seamlr only processes genuine external changes.