> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.oryxa.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Events: Real-Time Notifications in Synq

> Learn what Synq events are, when they fire, what an event payload looks like, and how to receive them in your systems via webhooks.

Synq emits a structured **event** every time something meaningful changes on the platform — a new order arrives, a product is updated, inventory shifts. Each event is the authoritative record of what happened, when it happened, and which user and organization triggered it. Your integrations, automations, and downstream systems can subscribe to these events via webhooks and react in real time, giving you a fully auditable and up-to-date picture of your commerce operations.

## Why events matter

Traditional polling-based integrations check for changes on a schedule, which means you are always slightly behind. With Synq's event-driven model, your systems receive a notification the moment something changes — no polling, no delay, no missed updates. Because every event carries a unique ID, a precise timestamp, and the full identity context of who triggered the action, you get end-to-end traceability across every operation without any extra instrumentation.

<CardGroup cols={2}>
  <Card title="Reliable delivery" icon="circle-check">
    If your endpoint is temporarily unavailable, Synq retries delivery automatically so you never miss a change.
  </Card>

  <Card title="Fully auditable" icon="clock-rotate-left">
    Every event records the exact user, organization, and tenant responsible for the action, giving you a complete audit trail.
  </Card>

  <Card title="Consistent structure" icon="brackets-curly">
    All events share the same envelope format regardless of type, so your consumer code stays simple and predictable.
  </Card>

  <Card title="Tenant-isolated" icon="lock">
    Your webhook endpoint only ever receives events that originated within your own Tenant — never events from other organizations on the platform.
  </Card>
</CardGroup>

## Common event types

| Event type           | Triggered when                                                     |
| -------------------- | ------------------------------------------------------------------ |
| `order.created`      | A new order is placed or imported into Synq                        |
| `order.updated`      | An existing order's status, line items, or details change          |
| `product.created`    | A new product is added to your catalog                             |
| `product.updated`    | A product's price, description, or attributes are modified         |
| `inventory.adjusted` | Stock levels change due to a sale, return, or manual adjustment    |
| `integration.synced` | A connected sales channel or ERP completes a synchronization cycle |

<Tip>
  Subscribe only to the event types your integration cares about. This keeps your handler logic focused and reduces unnecessary processing at your endpoint.
</Tip>

## Event payload structure

Every Synq event uses the same `DomainEvent` envelope regardless of type. The `payload` field contains the data specific to the event that occurred.

```json theme={null}
{
  "event_id": "e5d3a1f0-7c82-4b69-a91e-3f204dc8b07a",
  "event_type": "order.created",
  "timestamp": "2024-12-04T15:32:07.412Z",
  "tenant_id": "a3f8c120-4e72-4b91-9d63-1c5e7a09bf44",
  "org_id": "7b91d204-fc3a-48e1-a13c-3d88e6201bcd",
  "user_id": "c9a1e847-2f3d-4c10-b8e5-0a7d6f219abc",
  "role": "member",
  "payload": {
    "order_id": "ord_9f2a4c1e83b7",
    "status": "pending",
    "currency": "USD",
    "total": 149.99,
    "line_items": [
      {
        "sku": "SYNQ-SHIRT-M-BLK",
        "quantity": 2,
        "unit_price": 74.99
      }
    ],
    "created_at": "2024-12-04T15:32:06.998Z"
  }
}
```

**Envelope fields**

| Field        | Type              | Description                                                                  |
| ------------ | ----------------- | ---------------------------------------------------------------------------- |
| `event_id`   | string (UUID)     | Unique identifier for this event instance. Use it to deduplicate deliveries. |
| `event_type` | string            | The event category in `domain.action` format                                 |
| `timestamp`  | string (ISO 8601) | UTC timestamp of when the event was published                                |
| `tenant_id`  | string (UUID)     | The Tenant in which the event occurred                                       |
| `org_id`     | string (UUID)     | The Organization whose action triggered the event                            |
| `user_id`    | string (UUID)     | The user who performed the action                                            |
| `role`       | string            | The role of the user at the time of the action                               |
| `payload`    | object            | Event-specific data — structure varies by `event_type`                       |

<Note>
  The `event_id` is unique per event. Store it and check for duplicates in your handler to make your consumer idempotent — Synq may re-deliver an event if it does not receive a successful acknowledgement from your endpoint.
</Note>

## Receiving events via webhooks

To start receiving events, register a webhook endpoint in your Synq dashboard or through the API. Synq will `POST` each matching event to your URL as it occurs.

<Steps>
  <Step title="Create a webhook endpoint">
    Navigate to **Settings → Webhooks** in the dashboard and click **Add Endpoint**. Enter the HTTPS URL of your listener and select the event types you want to receive.
  </Step>

  <Step title="Verify the signature">
    Each delivery includes a `Synq-Signature` header you can use to confirm the request came from Synq and was not tampered with in transit. Validate it before processing the payload.
  </Step>

  <Step title="Acknowledge with a 2xx response">
    Return any `2xx` HTTP status code within 10 seconds to acknowledge delivery. If your endpoint returns a non-2xx status or times out, Synq retries with exponential back-off.
  </Step>

  <Step title="Process asynchronously for heavy work">
    If your handler needs to do significant work (database writes, third-party API calls), acknowledge the event immediately and enqueue the work for background processing. This prevents timeouts from triggering unnecessary retries.
  </Step>
</Steps>

For the full webhook setup guide, including signature verification and retry configuration, see [Webhooks](/guides/webhooks).

## Frequently asked questions

<Accordion title="How long does Synq retain events?">
  Synq retains all published events for 30 days. You can replay events within that window from the **Settings → Webhooks → Event Log** page in the dashboard, which is useful for debugging or recovering from a prolonged outage on your endpoint.
</Accordion>

<Accordion title="Can I filter events by order status or product category?">
  Currently, event subscriptions filter by event type. Fine-grained filtering on payload fields is on the roadmap. For now, filter in your handler after receiving the event.
</Accordion>

<Accordion title="Is there a rate limit on event delivery?">
  Synq delivers events as fast as your endpoint can acknowledge them. There is no artificial throttle, but your endpoint should respond quickly to avoid back-pressure on retries. See [Webhooks](/guides/webhooks) for guidance on handling high-throughput scenarios.
</Accordion>

<Accordion title="What happens if my endpoint is down for several hours?">
  Synq retries failed deliveries with exponential back-off for up to 72 hours. After that window, undelivered events are marked as failed. You can replay them manually from the Event Log.
</Accordion>