Webhooks API

Wallet authentication required for all webhook management endpoints except GET /webhooks/event-types. See Wallet Auth.

GET /webhooks/event-types

List available webhook event types. Public, no auth required.

POST /webhooks

Create a new webhook subscription.

Request Body

                
                JSON Body
            

{
  "url": "https://your-server.com/webhooks/vouch",        // Required — HTTPS callback URL
  "eventTypes": ["agent.tier_updated", "stake.deposited"],  // Required — array of event types
  "filterAgentPda": "BKq8rN4EwJQG..."                     // Optional — only events for this agent
}
        

GET /webhooks

List your webhook subscriptions.

PATCH /webhooks/:id

Update an existing webhook subscription.

Request Body

All fields are optional. Include only the fields you want to change.

                
                JSON Body
            

{
  "url": "https://new-server.com/webhooks/vouch",       // Optional — new HTTPS callback URL
  "eventTypes": ["agent.registered"],                    // Optional — replace subscribed events
  "filterAgentPda": "BKq8rN4EwJQG...",                  // Optional — set or clear (null) agent filter
  "active": false                                        // Optional — enable or disable the subscription
}
        

DELETE /webhooks/:id

Delete a webhook subscription.

POST /webhooks/:id/rotate-secret

Rotate the HMAC signing secret for a webhook.

GET /webhooks/:id/deliveries

View the delivery log for a webhook subscription.

Example Responses

`GET /webhooks/event-types`

            
            Response
        

{
  "event_types": [
    // Agent events
    "agent.registered",
    "agent.updated",
    "agent.reputation_updated",
    "agent.tier_updated",
    "agent.status_changed",
    "agent.suspended",
    "agent.reactivated",
    "agent.deactivated",
    "agent.closed",

    // Stake events
    "stake.deposited",
    "stake.withdrawn",
    "stake.withdrawal_requested",
    "stake.withdrawal_cancelled",
    "stake.closed"
  ]
}
    

`POST /webhooks`

            
            Response (201)
        

{
  "id": "wh_abc123",
  "secret": "whsec_k7G9mN2x...",
  "message": "Save the secret -- it will not be shown again. Use it to verify webhook signatures via X-Vouch-Signature header (HMAC-SHA256)."
}
    

`GET /webhooks`

            
            Response
        

{
  "subscriptions": [
    {
      "id": "wh_abc123",
      "url": "https://your-server.com/webhooks/vouch",
      "event_types": ["agent.tier_updated", "agent.reputation_updated"],
      "filter_agent_pda": "BKq8rN4EwJQG3R9FnLhSGqJ2tNkh8cVRxvNApj7hbfQM",
      "active": true,
      "created_at": "2026-03-10T08:00:00.000Z",
      "updated_at": "2026-03-10T08:00:00.000Z"
    }
  ]
}
    

Webhook Payload Example

            
            Delivered to your URL
        

{
  "id": "evt_d4e5f6",
  "type": "agent.tier_updated",
  "pda": "BKq8rN4EwJQG3R9FnLhSGqJ2tNkh8cVRxvNApj7hbfQM",
  "slot": 287654321,
  "timestamp": "2026-03-16T12:00:00Z",
  "data": {
    "agentPda": "BKq8rN4EwJQG3R9FnLhSGqJ2tNkh8cVRxvNApj7hbfQM",
    "owner": "7xKXtg2CW87d97TXJSDpHD4vMvnQ1985FchZRgCd9oPr",
    "previousTier": "basic",
    "newTier": "standard",
    "stakeAmount": 1000000000
  }
}

// Delivery headers:
//   X-Vouch-Signature: <HMAC-SHA256 hex digest>
//   X-Vouch-Timestamp: <unix timestamp>
//   X-Vouch-Event: agent.tier_updated
//
// HMAC is computed over "<unix_timestamp>.<json_payload>" for replay protection.
    