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

# Local servers

> Run Handler's local webhook server for development, demos, and integration testing.

# Run the local webhook server

Handler ships with a local webhook receiver for task push notifications, which
is useful for development work and integration testing.

## Run the push notification receiver

Start the local webhook receiver on the default port:

```bash theme={null}
handler server run push
```

```bash theme={null}
handler server run push --port 9001
```

By default it binds to `127.0.0.1:9000` and exposes these endpoints:

* `POST /webhook` receives task notifications
* `GET /webhook` returns a simple validation response
* `GET /notifications` lists received notifications
* `POST /notifications/clear` clears stored notifications

## Require a notification token

Agents send the token from the push config in the `X-A2A-Notification-Token`
header. Make the receiver reject any delivery that does not carry it:

```bash theme={null}
handler server run push --token local-secret
```

Use the same value as `--push-token` or `task notification set --token`. This
matters most when you bind the receiver beyond loopback with `--host`; without
`--token`, any POST is accepted.

## What a delivery looks like

An A2A v1.0 agent posts the event it just produced, wrapped the way the
streaming API wraps it: a `statusUpdate`, `artifactUpdate`, `task`, or
`message` object. Handler reads the task ID and state out of any of those and
also understands the older v0.3 shape with `id` and `status` at the top level.
Each received notification is printed with its task ID and state, and the
`GET /notifications` listing returns `task_id`, `state`, and the raw payload.

## End-to-end push notification test

1. Start the webhook receiver with `handler server run push --token local-secret`.

2. Send a message that creates a long-running task, pointing it at the receiver:

   ```bash theme={null}
   handler message send --server demo --text "Long job" --no-wait \
     --push-url http://127.0.0.1:9000/webhook --push-token local-secret
   ```

3. Inspect received events at `http://127.0.0.1:9000/notifications`, or watch
   them print in the receiver's terminal.

You can also attach the webhook to an existing task with
`handler task notification set`. This is a simple way to verify that an
agent's push flow works before wiring it into a real webhook consumer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.