Resource Subscriptions

How Subscriptions Work

Resource subscriptions allow you to receive webhook notifications whenever a resource's data changes. When you subscribe, you provide a callback URL. Agent Dojo will send an HTTP POST request to that URL each time the subscribed resource is updated, created, or deleted.

This enables real-time integrations where your application can react to data changes without polling the API.

Creating a Subscription

Subscribe to changes by providing a callback URL:

curl -X POST https://api.agentdojo.dev/mcp/subscribe \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-app.com/webhooks/resource-updates"
  }'

Response:

{
  "id": "sub_abc123",
  "callback_url": "https://your-app.com/webhooks/resource-updates",
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

Listing Active Subscriptions

Retrieve all active subscriptions for your API key:

curl -X GET https://api.agentdojo.dev/mcp/subscriptions \
  -H "X-API-Key: your-api-key"

Response:

{
  "subscriptions": [
    {
      "id": "sub_abc123",
      "callback_url": "https://your-app.com/webhooks/resource-updates",
      "status": "active",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Updating a Subscription

Update an existing subscription, for example to change the callback URL:

curl -X PUT https://api.agentdojo.dev/mcp/subscriptions/sub_abc123 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-app.com/webhooks/v2/resource-updates"
  }'

Removing a Subscription

Unsubscribe to stop receiving webhook notifications:

curl -X POST https://api.agentdojo.dev/mcp/unsubscribe \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "sub_abc123"
  }'

Resource-Specific Subscriptions

You can also subscribe and unsubscribe at the resource level using the resource-specific endpoints. This allows you to target notifications for individual resources.

curl -X POST https://api.agentdojo.dev/mcp/resources/subscribe \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "db://users",
    "callback_url": "https://your-app.com/webhooks/users-changed"
  }'

curl -X POST https://api.agentdojo.dev/mcp/resources/unsubscribe \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "db://users"
  }'

Webhook Delivery

When a subscribed resource changes, Agent Dojo sends an HTTP POST request to your callback URL with the following payload:

{
  "event": "resource.updated",
  "subscription_id": "sub_abc123",
  "resource": {
    "uri": "db://users",
    "name": "User Directory"
  },
  "timestamp": "2026-01-15T10:45:00Z"
}

Next Steps