2026-01-19 · Authensor

How to Set Up Custom Webhooks for AI Agent Events

SafeClaw by Authensor supports custom webhook integrations, allowing you to send AI agent safety events to any HTTP endpoint. This enables integration with internal tools, custom dashboards, workflow automation platforms, or any service that accepts webhook payloads. SafeClaw signs every payload for verification, supports retries, and works with both Claude and OpenAI agents. It ships with 446 tests and hash-chained audit logs.

Prerequisites

Step 1: Install SafeClaw

Initialize SafeClaw in your project:

npx @authensor/safeclaw

Step 2: Configure a Basic Webhook

Add webhook settings to .safeclaw/policy.yaml:

version: 1
default: deny


notifications:
  webhooks:
    - name: "custom-endpoint"
      url: "${WEBHOOK_URL}"
      method: POST
      events:
        - action.denied
        - action.prompted
        - action.allowed
        - audit.integrity_failure
      headers:
        Content-Type: "application/json"
        X-Source: "safeclaw"



rules:
  - action: file.read
    paths:
      - "src/**"
    decision: allow



- action: file.write
    paths:
      - "src/**"
    decision: prompt



- action: shell.execute
    decision: deny

Set the environment variable:

export WEBHOOK_URL="https://your-service.example.com/safeclaw-events"

Step 3: Understand the Webhook Payload

SafeClaw sends a JSON payload with this structure:

{
  "event_type": "action.denied",
  "timestamp": "2026-02-13T14:32:01.000Z",
  "data": {
    "action_type": "shell.execute",
    "target": "rm -rf /tmp/data",
    "decision": "denied",
    "agent": "gpt-4o",
    "policy_rule": "default:deny",
    "audit_hash": "a3f2c8e9b1d4f6a7c3e5d2b8f0a1c4e6",
    "previous_hash": "e7d3a9f2c1b5e8d4a6f0c2e9b3d7a1f5",
    "chain_position": 172,
    "project": "my-ai-app",
    "environment": "production"
  },
  "metadata": {
    "safeclaw_version": "1.2.0",
    "policy_version": 1,
    "hostname": "dev-workstation"
  }
}

Step 4: Enable Payload Signing

To verify that webhook payloads genuinely come from SafeClaw, enable HMAC signing:

notifications:
  webhooks:
    - name: "custom-endpoint"
      url: "${WEBHOOK_URL}"
      signing_secret: "${WEBHOOK_SECRET}"
      signing_algorithm: "sha256"
      signature_header: "X-SafeClaw-Signature"

SafeClaw computes an HMAC-SHA256 signature of the payload body using your secret and includes it in the X-SafeClaw-Signature header. Verify on your server:

const crypto = require('crypto');


function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Step 5: Configure Retries and Timeouts

Ensure reliable delivery with retry configuration:

notifications:
  webhooks:
    - name: "custom-endpoint"
      url: "${WEBHOOK_URL}"
      timeout_ms: 5000
      retry:
        max_attempts: 3
        backoff_strategy: "exponential"
        initial_delay_ms: 1000
        max_delay_ms: 30000
      on_failure: "log"

SafeClaw retries failed webhook deliveries with exponential backoff: 1 second, then 2 seconds, then 4 seconds. After 3 failures, it logs the event to the local audit log and continues.

Step 6: Add Multiple Webhooks

Route different events to different endpoints:

notifications:
  webhooks:
    - name: "security-team"
      url: "${SECURITY_WEBHOOK_URL}"
      events:
        - action.denied
        - audit.integrity_failure
      signing_secret: "${SECURITY_WEBHOOK_SECRET}"


- name: "analytics"
      url: "${ANALYTICS_WEBHOOK_URL}"
      events:
        - action.allowed
        - action.denied
        - action.prompted



- name: "automation"
      url: "${AUTOMATION_WEBHOOK_URL}"
      events:
        - action.denied
      filter:
        action_type: "shell.execute"

The filter option on the automation webhook sends only shell.execute denials, allowing you to trigger specific automated responses for the most dangerous action types.

Step 7: Test the Webhooks

Test all configured webhooks:

npx @authensor/safeclaw test-notify --channel webhooks

Test a specific webhook:

npx @authensor/safeclaw test-notify --channel webhooks --name security-team

Verify your endpoint receives the payload with the correct structure and signature. Then generate real events:

npx @authensor/safeclaw wrap -- node my-agent.js
npx @authensor/safeclaw audit --tail 5

Summary

SafeClaw's custom webhook support enables integration with any HTTP-capable service. HMAC payload signing ensures authenticity. Exponential backoff retries ensure reliable delivery. Event filtering and multi-webhook routing give you precise control over which events go where. SafeClaw is MIT licensed and open source.

Related Guides

Try SafeClaw

Action-level gating for AI agents. Set it up in your browser in 60 seconds.

$ npx @authensor/safeclaw