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

# Webhooks

> Planned event categories for integrating Woes changes with external systems.

Webhooks will let external systems react to Woes events without polling. Endpoint-level webhook documentation is not published yet.

## Planned event categories

<CardGroup cols={2}>
  <Card title="Conversations" icon="messages-square">
    Created, updated, resolved, assigned, or handed off.
  </Card>

  <Card title="Messages" icon="message-square">
    Customer, operator, or agent message created.
  </Card>

  <Card title="Customers" icon="user">
    Customer created, updated, or identity linked.
  </Card>

  <Card title="Issues" icon="list-todo">
    Issue created, updated, linked, or resolved.
  </Card>

  <Card title="Knowledge" icon="database">
    Source scan completed, failed, or changed coverage.
  </Card>

  <Card title="Agent" icon="bot">
    Agent answer created, handoff requested, or low-confidence event recorded.
  </Card>
</CardGroup>

## Future delivery docs should include

| Topic           | Needed detail                                                            |
| --------------- | ------------------------------------------------------------------------ |
| Event names     | Stable event type strings.                                               |
| Payload schemas | IDs, timestamps, workspace scope, and included resource fields.          |
| Signing         | How to verify the webhook came from Woes.                                |
| Retries         | Retry schedule, timeout behavior, and terminal failure state.            |
| Idempotency     | How receivers should dedupe deliveries.                                  |
| Ordering        | Whether events are ordered per workspace, resource, or delivery attempt. |

## Security expectations

Webhook receivers should verify signatures once signing details are published. Payloads should avoid secrets and include enough IDs to fetch additional data through authenticated APIs.

<Tip>
  Design webhook consumers to be idempotent. Even well-behaved webhook systems can deliver retries.
</Tip>