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

# Webhooks

> We push alerts to your servers immediately. No polling required.

<Note>
  Webhooks are strictly for **Enterprise** infrastructure. If you're running a massive deployment and need guaranteed HTTP delivery rather than maintaining WebSocket state, DM **[@alrerat](https://t.me/alrerat)** to set up a massive custom limit.
</Note>

## How the Webhook System Works

You register a specific URL endpoint with us. The millisecond an alert passes your customized criteria, we blast a `POST` payload containing the complete alert JSON straight to your server.

**Your only job:** Respond with a generic `200 OK` status code within 5 seconds to tell us you received it. (Failed deliveries are not retried, to prevent backing up the queue).

## Create a Webhook

Register your endpoint and tell us exactly what kind of alerts you want us to send.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    -H "Authorization: Bearer YOUR_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://your-production-app.com/api/polychads-hook",
      "categories": "crypto,world",
      "min_signal": 80
    }' \
    https://polychadsbot.xyz/api/v1/webhooks
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": "hook_8812jka...",
    "url": "https://your-production-app.com/api/polychads-hook"
  }
  ```
</ResponseExample>

### Configuration Fields

| Field        | Required | Description                                                                                              |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `url`        | Yes      | Your secure HTTPS endpoint. We do not support unencrypted HTTP delivery.                                 |
| `categories` | No       | Comma-separated list of genres you care about. If omitted, we ping you for everything.                   |
| `min_signal` | No       | Only send alerts with a Signal Score (0-100) equal to or above this number. Perfect for noise reduction. |

***

## The Payload Structure

When an alert fires, we will hit your `url` with a `POST` request. The body will be the standard [Alert Object](/reference/alert-object) formatted as JSON:

```json What lands on your server theme={null}
{
  "id": 2221,
  "alert_type": "fresh",
  "side": "BUY",
  "outcome": "Yes",
  "entry_price": 0.42,
  "usdc_value": 2100.0,
  "signal_score": 72,
  "event_title": "Will ETH hit $5000 by April?",
  "category": "crypto",
  "created_at": "2026-02-27 12:00:15"
}
```

***

## Manage Existing Webhooks

### List All Webhooks

See exactly what hooks are active on your current Enterprise key.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_KEY_HERE" \
  https://polychadsbot.xyz/api/v1/webhooks
```

### Delete a Webhook

Taking down a server? Clean up your hook so we stop hitting an empty endpoint.

```bash theme={null}
curl -X DELETE -H "Authorization: Bearer YOUR_KEY_HERE" \
  https://polychadsbot.xyz/api/v1/webhooks/{webhook_id}
```


## OpenAPI

````yaml POST /webhooks
openapi: 3.0.3
info:
  title: Polychads Alerts API
  version: '1.0'
  description: Real-time Polymarket insider trading alerts
servers:
  - url: https://polychadsbot.xyz/api/v1
security:
  - bearerAuth: []
paths:
  /webhooks:
    post:
      summary: Create Webhook
      description: Register a new HTTP endpoint to receive alert push delivery.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: Your HTTPS endpoint
                categories:
                  type: string
                  description: Comma-separated categories to filter (e.g. "crypto,world")
                min_signal:
                  type: integer
                  minimum: 0
                  maximum: 100
                  description: Minimum signal score threshold
      responses:
        '200':
          description: Created webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '403':
          description: Enterprise key required
      security:
        - bearerAuth: []
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
        categories:
          type: string
          nullable: true
        min_signal:
          type: integer
          nullable: true
        created_at:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key — get one from @chadsapibot on Telegram

````