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

# Webhooks

> Register HTTPS endpoints and receive message events without polling.

Webhooks push events to your server when something happens on the line — for example a message is received or sent. Use them when you want real-time updates instead of polling `GET /messages`.

## Prerequisites

* A Messages API key with the **`comms_webhooks`** scope.
* A public **HTTPS** URL that accepts `POST`.

## Register an endpoint

```bash theme={null}
curl -X POST "https://osis.co/api/v1/comms/webhooks" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.yourapp.com/comms",
    "events": ["message.received", "message.sent"]
  }'
```

**Scope:** `comms_webhooks`\
**Success:** **201** with the created webhook object.

## List endpoints

```bash theme={null}
curl "https://osis.co/api/v1/comms/webhooks" \
  -H "Authorization: Bearer $COMMS_API_KEY"
```

## Local development

1. Run your app with a `POST` handler that logs the body.
2. Tunnel with ngrok / Cloudflare Tunnel.
3. Register the tunnel URL as above.
4. Send a test message to your line (or fire a test from the API if available on your deployment).

## Handler checklist

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return **2xx** as soon as you accept the event. Do heavy work in a queue.
  </Accordion>

  <Accordion title="Treat delivery as at-least-once">
    The same event may arrive more than once. Make handlers idempotent on event id when present.
  </Accordion>

  <Accordion title="Keep secrets off the client">
    Webhook receivers belong on your server. Do not process hooks in a browser.
  </Accordion>
</AccordionGroup>

## Related

* [Create webhook](/messages-api/create-webhook)
* [List webhooks](/messages-api/list-webhooks)
* [List events](/messages-api/list-events) — poll delivery attempts if you need pull-based debugging