Webhook Management

Open Astra supports outbound webhooks that fire on agent events. Webhooks include a signing secret for verification, delivery history tracking, a test mode for development, and a dispatch inspector for debugging.

Creating webhooks

Each webhook subscribes to specific events and receives a unique signing secret.

bash

# Create a webhook
curl -X POST http://localhost:3000/webhooks \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["agent_completed", "tool.executed", "memory.written"],
    "description": "Notify external system on agent completions"
  }'

# Response (201 Created) — includes the signing secret
{
  "id": "wh_abc123",
  "url": "https://example.com/webhook",
  "events": ["agent_completed", "tool.executed", "memory.written"],
  "secret": "whsec_...",
  "enabled": true
}

Testing webhooks

Send a test payload to verify your endpoint is configured correctly.

bash

# Send a test webhook
curl -X POST http://localhost:3000/webhooks/wh_abc123/test \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# View delivery history
curl http://localhost:3000/webhooks/wh_abc123/deliveries \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Test mode

Enable test mode to intercept all webhook dispatches without actually sending them. Useful during development.

bash

# Enable test mode (intercepts all webhooks instead of dispatching)
curl -X POST http://localhost:3000/webhooks/test-mode/enable \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# View intercepted webhooks
curl http://localhost:3000/webhooks/test-mode/log \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Disable test mode (resume normal dispatch)
curl -X POST http://localhost:3000/webhooks/test-mode/disable \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Webhook inspector

The inspector provides a paginated view of webhook dispatch history including payloads, response status codes, response bodies, and latency.

bash

# Inspect webhook dispatch history (paginated)
curl "http://localhost:3000/webhook-inspector?limit=50&eventType=agent_completed" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Get details for a specific dispatch
curl http://localhost:3000/webhook-inspector/dispatch_abc123 \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Endpoint reference

Method	Endpoint	Description
`POST`	`/webhooks`	Create webhook
`GET`	`/webhooks`	List webhooks
`GET`	`/webhooks/:id`	Get webhook
`PUT`	`/webhooks/:id`	Update webhook
`DELETE`	`/webhooks/:id`	Delete webhook
`GET`	`/webhooks/:id/deliveries`	Delivery history
`POST`	`/webhooks/:id/test`	Send test payload
`POST`	`/webhooks/test-mode/enable`	Enable test mode
`POST`	`/webhooks/test-mode/disable`	Disable test mode
`GET`	`/webhooks/test-mode/log`	View intercepted webhooks
`DELETE`	`/webhooks/test-mode/log`	Clear test log
`GET`	`/webhook-inspector`	Dispatch history (limit default 50, max 200)
`GET`	`/webhook-inspector/:id`	Dispatch details