Webhook Specification

Overview

The Open Agent Passport (OAP) webhook system provides real-time notifications for agent passport events. This specification defines the webhook payload format, delivery mechanisms, and security requirements.

Webhook Events

Supported Events

Event Payload Structure

All webhook events follow this base structure:

{
  "id": "evt_1234567890",
  "type": "passport.created",
  "created_at": "2025-01-16T10:30:00Z",
  "data": {
    // Event-specific data
  },
  "api_version": "2025-01-16",
  "livemode": true
}

Event Payloads

Passport Events

passport.created

{
  "id": "evt_1234567890",
  "type": "passport.created",
  "created_at": "2025-01-16T10:30:00Z",
  "data": {
    "object": "passport",
    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
    "owner_id": "ap_org_456",
    "name": "Acme Support Bot",
    "status": "active",
    "capabilities": [
      {
        "id": "finance.payment.refund",
        "params": {"max_amount": 5000}
      }
    ],
    "assurance_level": "L4KYC",
    "created_at": "2025-01-16T10:30:00Z"
  },
  "api_version": "2025-01-16",
  "livemode": true
}

passport.updated

{
  "id": "evt_1234567891",
  "type": "passport.updated",
  "created_at": "2025-01-16T10:35:00Z",
  "data": {
    "object": "passport",
    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
    "changes": [
      {
        "field": "capabilities",
        "old_value": [{"id": "finance.payment.refund", "params": {"max_amount": 5000}}],
        "new_value": [{"id": "finance.payment.refund", "params": {"max_amount": 10000}}]
      }
    ],
    "updated_at": "2025-01-16T10:35:00Z"
  },
  "api_version": "2025-01-16",
  "livemode": true
}

passport.suspended

{
  "id": "evt_1234567892",
  "type": "passport.suspended",
  "created_at": "2025-01-16T10:40:00Z",
  "data": {
    "object": "passport",
    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
    "reason": "Policy violation detected",
    "suspended_at": "2025-01-16T10:40:00Z",
    "suspended_by": "ap_user_789"
  },
  "api_version": "2025-01-16",
  "livemode": true
}

Decision Events

decision.created

{
  "id": "evt_1234567893",
  "type": "decision.created",
  "created_at": "2025-01-16T10:45:00Z",
  "data": {
    "object": "decision",
    "decision_id": "dec_123456789",
    "agent_id": "ap_a2d10232c6534523812423eec8a1425c",
    "policy_id": "finance.payment.refund.v1",
    "allow": true,
    "reasons": [
      {
        "code": "capability_verified",
        "message": "Agent has required refund capability",
        "severity": "info"
      }
    ],
    "expires_in": 300,
    "context": {
      "amount": 5000,
      "currency": "USD",
      "transaction_id": "txn_123456"
    }
  },
  "api_version": "2025-01-16",
  "livemode": true
}

Webhook Security

Signature Verification

All webhooks include a signature header for verification:

X-APort-Signature: t=1640995200,v1=abc123def456...

Signature Format

X-APort-Signature: t={timestamp},v1={signature}

• t: Unix timestamp of the webhook
• v1: HMAC-SHA256 signature of the payload

Signature Generation

const crypto = require('crypto');

function generateSignature(payload, secret, timestamp) {
  const payloadString = JSON.stringify(payload);
  const signedPayload = `${timestamp}.${payloadString}`;
  const signature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  return `t=${timestamp},v1=${signature}`;
}

Signature Verification

function verifySignature(payload, signature, secret) {
  const [timestamp, signatureValue] = signature.split(',');
  const t = timestamp.split('=')[1];
  const v1 = signatureValue.split('=')[1];
  
  const expectedSignature = generateSignature(payload, secret, t);
  return expectedSignature === signature;
}

Webhook Delivery

Delivery Attempts

• Initial Attempt: Immediate delivery
• Retry Attempts: 3 retries with exponential backoff
• Retry Intervals: 1s, 5s, 30s, 5m, 30m, 2h, 6h, 12h
• Timeout: 30 seconds per attempt

Delivery Status

Response Requirements

Webhook endpoints must:

1. Return 200 OK for successful processing
2. Process within 30 seconds to avoid timeout
3. Handle duplicate events idempotently
4. Log delivery attempts for debugging

Webhook Configuration

Endpoint Registration

{
  "url": "https://example.com/webhooks/aport",
  "events": ["passport.created", "passport.updated"],
  "secret": "whsec_1234567890",
  "active": true,
  "created_at": "2025-01-16T10:00:00Z"
}

Event Filtering

Webhooks can be configured to receive specific events:

{
  "events": [
    "passport.created",
    "passport.suspended",
    "passport.revoked",
    "decision.created"
  ]
}

Error Handling

Webhook Failures

When webhook delivery fails:

1. Log Error: Record failure reason and timestamp
2. Retry Logic: Attempt delivery with exponential backoff
3. Dead Letter Queue: Store failed webhooks for manual review
4. Alerting: Notify administrators of persistent failures

Common Error Scenarios

Testing

Webhook Testing

Use the webhook testing endpoint:

curl -X POST https://api.aport.io/webhooks/test \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/test",
    "events": ["passport.created"]
  }'

Test Events

Test events are prefixed with test.:

• test.passport.created
• test.decision.created

Best Practices

Endpoint Implementation

1. Idempotency: Handle duplicate events gracefully
2. Async Processing: Process webhooks asynchronously
3. Error Handling: Implement proper error handling
4. Logging: Log all webhook processing attempts

Security

1. HTTPS Only: Always use HTTPS endpoints
2. Signature Verification: Always verify webhook signatures
3. Secret Management: Store webhook secrets securely
4. Rate Limiting: Implement rate limiting on webhook endpoints

Monitoring

1. Delivery Metrics: Track webhook delivery success rates
2. Performance Monitoring: Monitor endpoint response times
3. Error Tracking: Track and alert on webhook failures
4. Audit Logging: Log all webhook processing activities