Event Lifecycle

Every integration transaction in Avvyr is tracked as an IntegrationEvent — a database document that records the full lifecycle of an event from creation to delivery (or failure).

Event flow

1. Domain Event published (e.g. "order.created")
       │
2. Dispatcher receives the event
       │  Queries enabled integrations matching the event type
       │
3. Per matching integration:
       │  Creates IntegrationEvent (status: "queued")
       │  Enqueues command to Service Bus
       │
4. Worker picks up the command
       │  Updates status → "processing"
       │  Fetches fresh entity data
       │  Maps to external format
       │  Calls external API
       │
5a. Success → status: "success"
5b. Failure → status: "failed" → automatic retry or dead-letter

Event statuses

Automatic retries

Failed events are automatically retried with exponential backoff. The retry count is configurable per event type (0–5 retries).

Each retry creates a new IntegrationEvent linked to the original via resubmittedFromEventId. The original event is marked with isCurrentAttempt: false so the dashboard always shows the latest attempt.

Retries respect two control flags:

• resubmitEnabled — can be toggled per event to disable automatic retries
• forceStop — immediately halts all retry attempts for an event chain

Manual resubmission

Any failed event can be manually resubmitted from the integration dashboard or via the Management API:

POST /v1/integrations/events/{eventId}/retry
Authorization: Bearer <token>

This creates a new event, resets the status to queued, and re-enqueues it immediately (no delay).

Dead-letter handling

Events that exhaust all retries or encounter a fatal error are moved to a dead-letter queue. The platform monitors dead-letter queues and updates the corresponding IntegrationEvent with the dead-letter reason. These events are surfaced in the dashboard for manual investigation.

Event ordering

Events for the same integration are processed in order using Service Bus sessions. Each integration gets its own session ID, ensuring FIFO ordering per integration without blocking other integrations for the same tenant.

Monitoring via API

Use the Management API to query and monitor integration events:

# Get all events for an integration
POST /v1/integrations/events/filter
Authorization: Bearer <token>
Content-Type: application/json

{
  "integrationId": "integration-id",
  "status": "failed",
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-01-31T23:59:59Z"
}

# Get a specific event with full details
GET /v1/integrations/events/{eventId}
Authorization: Bearer <token>

# Cancel a stuck or unwanted event
POST /v1/integrations/events/{eventId}/cancel
Authorization: Bearer <token>

Communication logs

Every external API call made during event processing is logged. Logs include:

• HTTP method, URL, and status code
• Request and response headers
• Request and response bodies (large payloads offloaded to blob storage)
• Timing information
• Sensitive data is automatically masked (tokens, API keys, passwords)

These logs are visible in the integration dashboard and can be accessed via the event detail endpoint.