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

# Webhooks Overview

> Receive filing events from StockInsights in real time, instead of polling the API.

## Overview

Webhooks push events to your server the moment they happen, so you don't have to
poll the API for new filings and enrichments. When a subscribed event occurs,
StockInsights sends a signed HTTPS `POST` request to the endpoint you configure.

Every request carries a JSON [event payload](/api-reference/webhooks/events) and a
[signature](/api-reference/webhooks/verifying-signatures) so you can confirm it
came from StockInsights and was not tampered with in transit.

<Note>
  Webhooks are available on API plans. Add a destination from **Account Settings →
  Webhooks** in the dashboard.
</Note>

## Adding a destination

1. Open **Account Settings → Webhooks** in the dashboard.
2. Enter your endpoint URL. It must be served over HTTPS — plain `http://` is
   rejected.
3. Select the [events](/api-reference/webhooks/events) you want delivered. A
   destination with no events selected stays configured but receives nothing.
4. Save. Your **signing secret** is shown on the confirmation screen. You need it
   to [verify signatures](/api-reference/webhooks/verifying-signatures).

<Note>
  You can view and copy the signing secret again at any time from the Webhooks
  section — reveal it with the eye icon on the destination card. There is no need
  to rotate the secret just because you did not save it at creation.
</Note>

You get **one webhook destination per account**, and it receives events for every
market you subscribe to. Today that is **India (`IN`)** only.

## Managing a destination

From the Webhooks section you can:

* **Edit the endpoint URL** or change which events are delivered.
* **Rotate the signing secret.** The previous secret stops verifying immediately,
  so deploy the new secret to your endpoint before rotating, or right after.
* **Pause** the destination to stop delivery without deleting it, and **resume**
  it later. A paused destination receives nothing.
* **Delete** the destination. This removes the endpoint and its secret, and you
  stop receiving events immediately.

## Destination states

| State      | Meaning                                                   |
| ---------- | --------------------------------------------------------- |
| **Active** | Delivering events normally.                               |
| **Paused** | You paused delivery. No events are sent until you resume. |

## Endpoint requirements

Your endpoint must:

* Accept `POST` requests over **HTTPS**. Plain `http://` is rejected.
* Be reachable at a **public** address. Endpoints that resolve to a private,
  loopback, or otherwise non-public IP are rejected at delivery time, and the
  event is not retried.
* Respond directly, without redirecting. Redirects are **not** followed — a `3xx`
  is treated as a failed delivery.

Your endpoint should:

* [Verify the signature](/api-reference/webhooks/verifying-signatures) on every
  request before trusting the payload.
* Respond with a `2xx` status code as soon as it has accepted the event. Do the
  heavy processing asynchronously — StockInsights
  [retries](/api-reference/webhooks/delivery-and-retries) on non-`2xx` responses
  and times out slow endpoints.
* Be **idempotent**. Retries and at-least-once delivery mean the same event can
  arrive more than once; de-duplicate on the event `id`.

## Next steps

<CardGroup cols={2}>
  <Card title="Events & payloads" icon="bolt" href="/api-reference/webhooks/events">
    The events you can subscribe to and the shape of each payload.
  </Card>

  <Card title="Verifying signatures" icon="shield-check" href="/api-reference/webhooks/verifying-signatures">
    Confirm each request came from StockInsights.
  </Card>

  <Card title="Delivery & retries" icon="rotate" href="/api-reference/webhooks/delivery-and-retries">
    Retry schedule, timeouts, and which failures are retried.
  </Card>
</CardGroup>