> **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.

Event webhooks notify your server when a specific on-chain event is observed.

Each event webhook includes:

* A webhook endpoint (`name`, `url`, `enabled`, signing key)
* A single event subscription (`contract`, `topic0`, `decode_events`, optional `from_block`)

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

## Routes

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

## List Event Webhooks

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

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

Example response item:

```json
{
  "endpoint": {
    "id": "a5113c41-18f3-45a7-b1cd-3acbf8a3f489",
    "name": "example-event-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,
    "contract": "0x32de7f85388d15365f87d96c94241a43880eba26",
    "topic0": "0xcf3dc07771cc79f08443885798a1e22d38a980af01eb51c3fd4b475afa81467b",
    "decode_events": true,
    "from_block": 31114,
    "status": "active",
    "created_at": "2026-02-20T19:08:44.806539Z",
    "updated_at": "2026-02-20T19:08:44.806539Z"
  },
  "user_id": "G8df2r3YFnrG5gwpn7rzD"
}
```

## Create Event Webhook

```bash
curl -X POST http://localhost:8000/api/v1/event-webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "name": "My Mint Watcher",
    "url": "https://3c4a-142-160-238-84.ngrok-free.app/webhook",
    "contract": "0x66EC845C0B07D1728B1b14921D561fe7963A5Ab8",
    "topic0": "0xcf3dc07771cc79f08443885798a1e22d38a980af01eb51c3fd4b475afa81467b",
    "decode_events": true
  }'
```

Example response:

```json
{
  "endpoint": {
    "id": "588793f2-42bf-496f-ac46-a7cd7cd3bc08",
    "name": "My Mint Watcher",
    "url": "https://3c4a-142-160-238-84.ngrok-free.app/webhook",
    "signing_key": "whsec_0f71ea604c43cea27fc8ccc37bbb523055b0cbf3b9927f1e5e516cc8d1f84e0a",
    "enabled": true,
    "created_at": "2026-02-20T19:08:44.806539Z",
    "updated_at": "2026-02-20T19:08:44.806539Z"
  },
  "subscription": {
    "id": "ec849e0b-8bf2-4d8a-ad4b-09afc0783e00",
    "endpoint_id": "588793f2-42bf-496f-ac46-a7cd7cd3bc08",
    "chain_name": "zksyncos_prividium",
    "chain_id": 8022834,
    "contract": "0x66ec845c0b07d1728b1b14921d561fe7963a5ab8",
    "topic0": "0xcf3dc07771cc79f08443885798a1e22d38a980af01eb51c3fd4b475afa81467b",
    "decode_events": true,
    "from_block": 18128,
    "status": "active",
    "created_at": "2026-02-20T19:08:44.806539Z",
    "updated_at": "2026-02-20T19:08:44.806539Z"
  },
  "user_id": "rCNv_z0CebSRbJd01N"
}
```

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

## Get Event Webhook

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

`signing_key` is not returned on read operations.

## Update Event Webhook

Update mutable endpoint fields such as `url`, `enabled`, and `decode_events`.

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

For event webhooks, subscription fields `contract`, `topic0`, and chain cannot be changed. `decode_events` may be
updated without recreating the webhook.

## Delete Event Webhook

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

Response: `204 No Content`

## Validation Rules

* `contract` must be a valid EVM address.
* `topic0` must be a valid 32-byte hash.
* `decode_events` must be a boolean.
* Invalid input returns `400 BadRequest`.
* Unknown or unauthorized IDs return `404 NotFound`.

## Related

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