> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.prividium.com/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

Address webhooks notify your server when activity occurs for one or more monitored addresses.

Each address webhook includes:

* A webhook endpoint (`name`, `url`, `enabled`, signing key)
* An address subscription (address set + optional `from_block`)

:::info[Authentication]
All routes require authentication.
:::

## Routes

| Method   | Path                                     |
| -------- | ---------------------------------------- |
| `POST`   | `/api/v1/address-webhook`                |
| `GET`    | `/api/v1/address-webhook`                |
| `GET`    | `/api/v1/address-webhook/{id}`           |
| `PATCH`  | `/api/v1/address-webhook/{id}`           |
| `DELETE` | `/api/v1/address-webhook/{id}`           |
| `GET`    | `/api/v1/address-webhook/{id}/addresses` |
| `POST`   | `/api/v1/address-webhook/{id}/addresses` |
| `DELETE` | `/api/v1/address-webhook/{id}/addresses` |

## List Address Webhooks

Use list to discover endpoint UUIDs used by get, update, delete, address management, and key rotation routes.

```bash
curl "http://localhost:8000/api/v1/address-webhook?limit=20&offset=0" \
  -H "Authorization: Bearer <TOKEN>"
```

Example response item:

```json
{
  "endpoint": {
    "id": "a5113c41-18f3-45a7-b1cd-3acbf8a3f489",
    "name": "example-address-webhook",
    "url": "https://3c4a-142-160-238-84.ngrok-free.app/webhook",
    "enabled": true,
    "created_at": "2026-02-20T19:08:44.806539Z",
    "updated_at": "2026-02-20T19:08:44.806539Z"
  },
  "subscription": {
    "id": "9592c92a-19f7-4ee4-9ed1-945293f6fd2d",
    "endpoint_id": "a5113c41-18f3-45a7-b1cd-3acbf8a3f489",
    "chain_name": "prividium_testnet",
    "chain_id": 8022834,
    "from_block": 31114,
    "status": "active",
    "created_at": "2026-02-20T19:08:44.806539Z",
    "updated_at": "2026-02-20T19:08:44.806539Z"
  },
  "user_id": "G8df2r3YFnrG5gwpn7"
}
```

## Create Address Webhook

```bash
curl -X POST http://localhost:8000/api/v1/address-webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "name": "webhook-address",
    "url": "https://3c4a-142-160-238-84.ngrok-free.app/webhook",
    "addresses": [
      "0x0e9c68525eA0739f9f013c1042cFe8CD1f323C19",
      "0x5A39B3f95812DC1E902ab745A2FB5894a8ab8897"
    ]
  }'
```

Example response:

```json
{
  "endpoint": {
    "id": "7ef711b5-26aa-4989-860a-9305f3f3715f",
    "name": "webhook-address",
    "url": "https://3c4a-142-160-238-84.ngrok-free.app/webhook",
    "signing_key": "whsec_38f30005e37490b6656b278f99547a9a9453ca4d472feefd0983054802a5373c",
    "enabled": true,
    "created_at": "2026-02-20T19:08:44.806539Z",
    "updated_at": "2026-02-20T19:08:44.806539Z"
  },
  "subscription": {
    "id": "79657e71-403a-4be0-94aa-ca83b03d9d98",
    "endpoint_id": "7ef711b5-26aa-4989-860a-9305f3f3715f",
    "chain_name": "zksyncos_prividium",
    "chain_id": 8022834,
    "from_block": 19122,
    "status": "active",
    "created_at": "2026-02-20T19:08:44.806539Z",
    "updated_at": "2026-02-20T19:08:44.806539Z"
  },
  "user_id": "Rz4ovpmb-1--qLH3HZ"
}
```

:::info[Key handling]
Signing key is returned only once.
:::

## Get Address Webhook

```bash
curl -X GET http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID> \
  -H "Authorization: Bearer <TOKEN>"
```

`signing_key` is not returned on read operations.

## Update Address Webhook

```bash
curl -X PATCH http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "url": "https://3c4a-142-160-238-84.ngrok-free.app/webhook"
  }'
```

## Delete Address Webhook

```bash
curl -X DELETE http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID> \
  -H "Authorization: Bearer <TOKEN>"
```

Response: `204 No Content`

## Manage Addresses

### List Addresses

```bash
curl -X GET http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID>/addresses \
  -H "Authorization: Bearer <TOKEN>"
```

Example response:

```json
{
  "addresses": ["0x0e9c68525ea0739f9f012c1042cfe8cd1f323c19", "0x5a39b3f95812dc1e942ac757a8fb5894a8ab8897"]
}
```

### Add Addresses

At least one address is required.

```bash
curl -X POST http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID>/addresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "addresses": [
      "0x1111111111111111111111111111111111111111"
    ]
  }'
```

Response: `204 No Content`

### Remove Addresses

```bash
curl -X DELETE http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID>/addresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "addresses": [
      "0x1111111111111111111111111111111111111111"
    ]
  }'
```

Response: `204 No Content`

## Validation Rules

* All addresses must be valid EVM addresses.
* Unknown or unauthorized IDs return `404 NotFound`.

## Related

* [Rotating Signing Keys](/developers/webhooks/rotating-signing-keys)
* [Verifying Signatures](/developers/webhooks/verifying-signatures)