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

# Subscribe to Events

> Receive real-time events from partners

<Info>
  Subscriptions act as filters for events addressed to you. Events sent to your Client ID but outside your subscriptions will queue based on your plan's retention period (up to 30 days). Subscribe later to automatically receive queued events.
</Info>

## Usage

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const subscription = await client.subscribe("order/*", {
      autoAck: false
    });

    subscription.on(async (event) => {
      console.log("Received:", event.payload);
      await subscription.ack(event.idem, event.block);
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    subscription = await client.subscribe("order/*", {
      "auto_ack": False
    })

    async def handle_event(event):
        print(f"Received: {event.payload}")
        await subscription.ack(event.idem, event.block)

    subscription.on(handle_event)
    ```
  </Tab>
</Tabs>

## Parameters

| Parameter   | Type     | Required | Description                                |
| ----------- | -------- | -------- | ------------------------------------------ |
| `eventName` | `string` | Yes      | Event path (supports wildcards: `order/*`) |
| `options`   | `object` | No       | Subscription options                       |

## Options

| Option         | Type      | Default | Description             |
| -------------- | --------- | ------- | ----------------------- |
| `autoAck`      | `boolean` | `true`  | Auto-acknowledge events |
| `appSecretKey` | `string`  | `null`  | Custom decryption key   |

## Event Structure

```javascript theme={null}
{
  idem: "unique-event-id",
  block: "block-id",
  eventName: "order/created",
  payload: { /* your data */ },
  timestamp: 1634567890123,
  sender: "sender's appId",
  metadata: {
    $internal: {
      // EnSync internal metadata
      // e.g., message_size, replay_info, etc.
    }
  }
}
```