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

# Configuring Event Delivery

> Set up Webhook or SSE event delivery for your WSAPI Cloud instances

After pairing your instance, configure how you want to receive event notifications (messages, chats, group updates, etc.) at [wsapi.chat/app/settings](https://wsapi.chat/app/settings).

In the **Instance Setting Defaults** section, you can select the Event Delivery mode (Webhook or Pull Mode with SSE).

## Event delivery modes

<Tabs>
  <Tab title="Webhook Mode">
    In Webhook mode, WSAPI Cloud sends events to a public endpoint you specify via HTTP POST requests with a JSON payload.

    ### Configuration

    | Field                      | Description                                         | Required    |
    | -------------------------- | --------------------------------------------------- | ----------- |
    | **Webhook URL**            | Your public HTTPS endpoint that will receive events | Yes         |
    | **Event Signature Secret** | Secret used to sign webhook events for verification | Recommended |

    <Warning>
      Always configure signature verification for webhook events to validate the legitimacy of incoming webhook calls. Without it, anyone who discovers your webhook URL could send fake events.
    </Warning>

    ### How it works

    1. An event occurs on your WhatsApp instance (e.g., new message received)
    2. WSAPI sends a POST request to your webhook URL with the event payload
    3. Your server processes the event and returns a `200` response

    See the [Events overview](/events/overview) for payload formats and delivery details.
  </Tab>

  <Tab title="Pull Mode (SSE)">
    In pull mode, your application connects to WSAPI using **Server-Sent Events (SSE)**. This eliminates the need for a public endpoint to receive webhooks.

    ### Configuration

    | Field                      | Description                                         | Required    |
    | -------------------------- | --------------------------------------------------- | ----------- |
    | **Event Signature Secret** | Secret used to sign webhook events for verification | Recommended |

    <Warning>
      In SSE mode, signing events is still recommended to ensure the integrity of the event stream. Always verify signatures on incoming events to protect against tampering or spoofing.
    </Warning>

    ### How it works

    1. Your app opens a persistent SSE connection to WSAPI
    2. Events are streamed to your app in real time as they occur
    3. If the connection drops, your app reconnects and resumes

    <Info>
      We recommend using this mode with one of our official SDKs, which include a proper SSE client implementation. If your language isn't supported, refer to the SDK's implementation as a reference.
    </Info>

    ### Supported SDKs

    <CardGroup cols={3}>
      <Card title="Node.js" icon="js" href="/sdks/nodejs">
        TypeScript/JavaScript SDK
      </Card>

      <Card title=".NET" icon="microsoft" href="/sdks/dotnet">
        C# / .NET 7+ SDK
      </Card>

      <Card title="Python" icon="python" href="/sdks/python">
        Python SDK
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Per-instance vs. global settings

The event delivery mode you select in the dashboard applies as a default for all instances. However, you can override this on a per-instance basis under the **Instance Settings** section in the instance details page. This allows you to have different instances using different delivery modes if needed. When overriding settings for an instance, event filtering will also be applied based on the instance's specific configuration.