Event Webhooks API

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)

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.

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

Example response item:

{
  "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

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:

{
  "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"
}

Get Event Webhook

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.

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

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.