Webhook Integration

Overview

Any platform that can send an HTTP POST request can integrate with Cacuda Automod. The webhook integration is the most flexible way to connect — use it for custom CMS platforms, forums, chat applications, or any system that produces user-generated content.

Webhook URL

Each automod has a unique webhook URL in the format:

https://api.cacuda.com/hooks/{webhookPath}

Find this URL on your automod's detail page after activating it.

Payload Format

Send a JSON body with a content field containing the text to moderate:

{
  "content": "The text content to moderate",
  "metadata": {
    "author": "user-123",
    "source": "forum",
    "postId": "abc-456",
    "callbackUrl": "https://your-site.com/api/cacuda-callback"
  }
}

The metadata object is optional and passed through to your action nodes.

HMAC Signing

All webhook requests must be signed with HMAC-SHA256 to verify authenticity. Compute the signature over the raw JSON body using your webhook secret:

# Generate the HMAC signature
SIGNATURE=$(echo -n '$PAYLOAD' | openssl dgst -sha256 -hmac '$WEBHOOK_SECRET' | cut -d' ' -f2)

# Include it in the x-cacuda-signature header
curl -X POST https://api.cacuda.com/hooks/your-webhook-path \
  -H "Content-Type: application/json" \
  -H "x-cacuda-signature: $SIGNATURE" \
  -d '$PAYLOAD'

Example: curl

Full example sending a test payload with signature:

#!/bin/bash
WEBHOOK_SECRET="your-webhook-secret"
WEBHOOK_URL="https://api.cacuda.com/hooks/your-webhook-path"
PAYLOAD='{"content":"Hello world, check this out!","metadata":{"source":"test"}}'

SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | cut -d' ' -f2)

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "x-cacuda-signature: $SIGNATURE" \
  -d "$PAYLOAD"

Response Format

Cacuda returns a JSON response with the execution details:

{
  "executionId": "exec_abc123",
  "status": "completed",
  "creditsUsed": 1,
  "actionsTaken": ["approve"],
  "durationMs": 245
}

Callback URLs

If your action nodes have a callbackUrl configured (either on the node itself or passed in the payload metadata), Cacuda will POST the approve/reject result back to that URL.

This enables asynchronous moderation — submit content, let Cacuda process it, and receive the decision at your callback endpoint.

Error Handling

Common error responses you may encounter: