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

# Use Webhooks

> Deliver Trio events via webhook callbacks

## Goal

Receive Trio events through webhooks and process them safely in production.

## When to Use

Use webhooks when your system should react to events without polling loops.

Typical cases:

* trigger alerts
* start downstream workflows
* update external systems

## Setup Flow

1. Expose a public HTTPS endpoint that accepts `POST` JSON.
2. Start `live-monitor` or `live-digest` with `webhook_url`.
3. Return `2xx` quickly from your handler.
4. Process heavy work asynchronously.

## Minimal Handler Pattern

```python theme={null}
@app.post("/trio-webhook")
async def trio_webhook(request: Request):
    payload = await request.json()
    # enqueue payload for async processing
    return {"ok": True}
```

## Event Types to Handle

Common `type` values:

* `job_started`
* `job_stopped`
* `watch_triggered`
* `summary_generated`
* `error`

## Reliability Requirements

* Use idempotency logic to avoid duplicate side effects.
* Log `type`, `timestamp`, and `job_id` (if present).
* Retry downstream actions with bounded backoff.
* Keep webhook handlers fast; do not block on long work.

## Recovery Pattern

If continuous coverage is required:

1. detect terminal state (`job_stopped`)
2. create a replacement job
3. persist and monitor the new `job_id`

## Next Steps

* Troubleshoot deliveries: [Debugging Playbook](/guides/debugging)
* Compare delivery modes: [Choose Your Workflow](/start-here/choose-workflow)
* Endpoint behavior: [Live Monitor](/api-reference/live-monitor)