Tutorial: Webhook Subscriptions

Platform

Data source: Internal

Overview

Webhook Subscriptions wraps Internal, handling authentication, pagination, and rate limits for you. This tutorial covers all 7 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-webhooks": {
      "url": "https://context.gnist.ai/mcp/webhooks/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (7)

`subscribe`

Create a webhook subscription for data change notifications. When data matching the entity_type changes, a signed POST request will be sent to the callback_url with the change payload. The returned secret is used to verify webhook signatures (HMAC-SHA256). Store it securely — it is only shown once. Args: api_key: Your Gnist API key. entity_type: The type of entity to monitor for changes. callback_url: HTTPS endpoint to receive webhook deliveries. Returns: Subscription details including id and signing secret, or error.

Parameter	Type	Required	Description
`api_key`	string	required	Your Gnist API key (starts with 'gnist_').
`entity_type`	string	required	Entity type to subscribe to (e.g. 'brreg_company', 'doffin_tender').
`callback_url`	string	required	HTTPS URL where webhook events will be delivered.

curl -X POST "https://context.gnist.ai/mcp/webhooks/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "subscribe", "arguments": {"api_key": "example", "entity_type": "'brreg_company'", "callback_url": "https://example.com"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/webhooks/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'api_key': 'example',
                          'callback_url': 'https://example.com',
                          'entity_type': "'brreg_company'"},
            'name': 'subscribe'}},
)
print(resp.json())

`unsubscribe`

Remove a webhook subscription (soft delete). The subscription will stop receiving deliveries immediately. Args: api_key: Your Gnist API key. subscription_id: The subscription UUID to deactivate. Returns: Confirmation or error if subscription not found.

Parameter	Type	Required	Description
`api_key`	string	required	Your Gnist API key (starts with 'gnist_').
`subscription_id`	string	required	UUID of the subscription to remove.

curl -X POST "https://context.gnist.ai/mcp/webhooks/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "unsubscribe", "arguments": {"api_key": "example", "subscription_id": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/webhooks/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'api_key': 'example', 'subscription_id': '12345'},
            'name': 'unsubscribe'}},
)
print(resp.json())

`list_subscriptions`

List all active webhook subscriptions for your API key. Returns subscriptions with their entity type, callback URL, and status. Args: api_key: Your Gnist API key. Returns: List of active subscriptions.

Parameter	Type	Required	Description
`api_key`	string	required	Your Gnist API key (starts with 'gnist_').

curl -X POST "https://context.gnist.ai/mcp/webhooks/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_subscriptions", "arguments": {"api_key": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/webhooks/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'api_key': 'example'}, 'name': 'list_subscriptions'}},
)
print(resp.json())

`reset_subscription`

Reset a subscription's circuit breaker. When a subscription has too many consecutive delivery failures, its circuit breaker opens and deliveries are paused. Use this tool to manually re-enable delivery. Args: api_key: Your Gnist API key. subscription_id: The subscription UUID to reset. Returns: Confirmation or error if subscription not found.

Parameter	Type	Required	Description
`api_key`	string	required	Your Gnist API key (starts with 'gnist_').
`subscription_id`	string	required	UUID of the subscription to reset.

curl -X POST "https://context.gnist.ai/mcp/webhooks/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "reset_subscription", "arguments": {"api_key": "example", "subscription_id": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/webhooks/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'api_key': 'example', 'subscription_id': '12345'},
            'name': 'reset_subscription'}},
)
print(resp.json())

`list_deliveries`

List recent webhook deliveries. Shows delivery attempts with status (pending/delivered/failed), number of attempts, and HTTP response codes. Args: api_key: Your Gnist API key. subscription_id: Optional filter to a specific subscription. limit: Maximum deliveries to return (1-200, default 50). Returns: List of recent deliveries.

Parameter	Type	Required	Description
`api_key`	string	required	Your Gnist API key (starts with 'gnist_').
`subscription_id`	any	optional	Filter to a specific subscription UUID. Omit for all subscriptions.
`limit`	integer	optional	Maximum number of deliveries to return. (default: `50`)

curl -X POST "https://context.gnist.ai/mcp/webhooks/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_deliveries", "arguments": {"api_key": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/webhooks/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'api_key': 'example'}, 'name': 'list_deliveries'}},
)
print(resp.json())

`get_webhook_metrics`

Get webhook delivery metrics. Returns aggregated delivery statistics per subscription: total deliveries, success/failure/pending counts, and last delivery timestamp. Args: api_key: Your Gnist API key. subscription_id: Optional filter to a specific subscription. hours: Time window in hours (1-720, default 24). Returns: Delivery metrics grouped by subscription.

Parameter	Type	Required	Description
`api_key`	string	required	Your Gnist API key (starts with 'gnist_').
`subscription_id`	any	optional	Filter to a specific subscription UUID. Omit for all subscriptions.
`hours`	integer	optional	Time window in hours (default 24, max 720). (default: `24`)

curl -X POST "https://context.gnist.ai/mcp/webhooks/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_webhook_metrics", "arguments": {"api_key": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/webhooks/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'api_key': 'example'}, 'name': 'get_webhook_metrics'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/webhooks/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/webhooks/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use list_subscriptions to find items, then get_webhook_metrics to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Webhook Subscriptions provide?

Manage webhook subscriptions for push-based data delivery — subscribe to entity changes, list subscriptions, and track delivery status. It exposes 7 tools: subscribe, unsubscribe, list_subscriptions, reset_subscription, list_deliveries, get_webhook_metrics, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Webhook Subscriptions API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 7 tools.

Getting Started with Webhook Subscriptions