Actions Webhooks

1. External Event
   Your system detects an event (e.g., new review, form submission, CRM update)

2. Send Signed Webhook
   Your server (or the SDK) sends a signed HTTP POST to AgentPress
   with the event payload and Svix signature headers

3. AgentPress Creates Action
   The webhook is verified, deduplicated, and stored as a
   pending action linked to the matching action rule

4. Agent Processes Action
   The configured agent picks up the pending action, executes
   its instructions, and pauses if a tool requires approval

5. Post-Event Callbacks (optional)
   AgentPress sends signed lifecycle callbacks to your configured
   endpoint for pending approval, approved/running, and terminal events

6. Your Server Handles Lifecycle Events
   Your server verifies the callback signature, shows approval requests,
   and reacts to completed, failed, rejected, or expired actions

https://api.agent.press/webhooks/actions/{orgId}/{webhookIdentifier}

interface WebhookPayload {
  // Event type identifier (e.g., "review.created", "email.received")
  eventType: string;

  // Unique ID from the external system (used for idempotency)
  externalId: string;

  // Optional: User to run the action as.
  // If provided with authProvider, resolves via external auth.
  // If a valid UUID without authProvider, resolves via direct lookup.
  // If omitted, falls back to the webhook's configured default user.
  userId?: string;

  // Optional: External auth provider name (e.g., "google_business").
  // Required when userId is an external ID (not a UUID).
  authProvider?: string;

  // Optional: Override the default action rule
  actionRuleId?: string;

  // Optional: Additional per-request instructions for the agent
  instructions?: string;

  // Custom data specific to your integration
  data: {
    [key: string]: unknown;
  };
}

{
  "eventType": "review.created",
  "externalId": "review-12345",
  "userId": "external-user-456",
  "data": {
    "reviewText": "Great service! The staff was super helpful.",
    "rating": 5,
    "locationName": "Downtown Location",
    "reviewerName": "Jane Smith",
    "reviewDate": "2025-01-16T17:30:00Z"
  }
}

const crypto = require("crypto");

const ORG_ID = "your-org-id-here";
const WEBHOOK_IDENTIFIER = "my_webhook";
const SECRET = "your-secret-here"; // Base64 part after whsec_
const API_URL = "http://localhost:3001";

async function sendTestWebhook() {
  const msgId = "msg_" + crypto.randomBytes(16).toString("hex");
  const timestamp = Math.floor(Date.now() / 1000).toString();

  const payload = {
    eventType: "review.created",
    externalId: `review-${Date.now()}`, // Unique for idempotency
    userId: "test-user-123",
    data: {
      reviewText: "This place is amazing! The staff was super helpful.",
      rating: 5,
      locationName: "Downtown Location",
      reviewerName: "Jane Smith",
      reviewDate: new Date().toISOString(),
    },
  };

  const payloadString = JSON.stringify(payload);
  const toSign = `${msgId}.${timestamp}.${payloadString}`;
  const signature = crypto
    .createHmac("sha256", Buffer.from(SECRET, "base64"))
    .update(toSign)
    .digest("base64");

  const response = await fetch(
    `${API_URL}/webhooks/actions/${ORG_ID}/${WEBHOOK_IDENTIFIER}`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "svix-id": msgId,
        "svix-timestamp": timestamp,
        "svix-signature": `v1,${signature}`,
      },
      body: payloadString,
    },
  );

  const result = await response.json();
  console.log("Status:", response.status);
  console.log("Response:", result);
}

sendTestWebhook().catch(console.error);

node test-webhook.js

{
  "success": true,
  "actionId": "uuid-of-created-action"
}

{
  "success": true,
  "actionId": "uuid-of-existing-action",
  "alreadyExists": true
}

{
  "success": true,
  "skipped": true,
  "reason": "No action rule configured"
}

{
  "error": "No user resolved — provide userId (+ authProvider) in the webhook payload, or configure a default user on the webhook in the console."
}

# Terminal 1: Start your API server
bun dev

# Terminal 2: Create a tunnel to your API port
ngrok http 3001

https://abc123.ngrok.io/webhooks/actions/{orgId}/{webhookIdentifier}