You can set up webhooks for common events and actions from the moderation queue. This is useful if you want to integrate the queue with your own systems. Webhooks are configured under integrations in your dashboard
 The webhook payload will be sent as a POST request to the URL you specify.
The webhooks require your server to respond with a 200 status code within 5 seconds, otherwise they will be retried. Webhooks are tried at most 5 times.

​
Webhook payload


​
id
string
required
The unique id of the event.
​
type
string
required
The type of the webhook. Can be QUEUE_ITEM_NEW, QUEUE_ITEM_ACTION or QUEUE_ITEM_COMPLETED.
​
timestamp
number
required
The timestamp of when the webhook was sent.
​
item
Item Object
required
The content item that triggered the webhook.
​
queue
object
The queue that the content item is in.
​
action
object
The action that was taken on the content item if the type is QUEUE_ITEM_ACTION.

Webhook payload example
{
  "id": "123",
  "type": "QUEUE_ITEM_ACTION",
  "timestamp": 1691496019049,
  "item": {
    "id": "644718a7fc78a41ec9f34a6d",
    "flagged": true,
    "labels": [
      {
        "label": "nsfw/UNSAFE",
        "score": 0.7266457980882517,
        "flagged": true,
        "manual": false
      },
      {
        "label": "nsfw/SENSITIVE",
        "score": 0.01,
        "flagged": false,
        "manual": false
      }
    ],
    "language": "en",
    "content": "Example content",
    "timestamp": 1691496019049,
    "metadata": {
      "key": "value"
    }
  },
  "queue": {
    "id": "123",
    "name": "My queue"
  },
  "action": {
    "id": "123",
    "name": "Remove content",
    "value": "spam"
  },
  "contextId": "demo-context",
  "authorId": "author-123"
}

​
Webhook signing

You can verify that the webhook is coming from us by comparing the signature of the payload with the signature provided in the modapi-signature header.
The signature is a HMAC SHA256 hash of the payload using your webhook secret as the key. Find you webhook secret under integrations in your dashboard. 
import ModerationApi from "@moderation-api/sdk";

const moderationApi = new ModerationApi({
  key: PROJECT_API_KEY,
});

export async function POST(request: Request) {
  try {
    const body = await request.text();
    const headersList = await headers();
    const webhookSignatureHeader = headersList.get("modapi-signature");

    if (!webhookSignatureHeader) {
      return NextResponse.json(
        { error: "No signature header" },
        { status: 400 }
      );
    }

    const payload = await moderationApi.webhooks.constructEvent(
      Buffer.from(body),
      webhookSignatureHeader,
      process.env.MODAPI_WEBHOOK_SECRET!
    );

    return NextResponse.json({ received: true });
  } catch (error) {
    console.error("Error processing webhook:", error);
    return NextResponse.json(
      { error: "Error processing webhook" },
      { status: 400 }
    );
  }
}

​
Preventing replay attacks

To prevent replay attacks, you can use the timestamp in the payload of the webhook to ensure that the webhook is not older than 5 minutes.

​
Troubleshooting

​
Check events log

If webhooks aren’t working as expected, first check the events log in your dashboard to see detailed information about webhook delivery attempts and any failures.

​
Allow Moderation API

You may find that some hosting providers and security services block webhook traffic. For example Cloudflare’s Bot Fight mode will present a challenge instead of allowing the webhook.

​
Common blocking scenarios

  • Bot Fight Mode / Super Bot Fight Mode is enabled
  • WAF Managed Rules active
  • Custom security rules

​
Choose your solution based on your plan

✅ Use Security Rules (Recommended)
  1. Go to your Cloudflare dashboard
  2. Select your domain
  3. Navigate to Security → Security rules
  4. Create a custom rule:
    • Name: “Moderation API Webhooks”
    • Field: User Agent
    • Operator: starts with
    • Value: ModAPI/
    • Action: Skip All Super Bot Fight Mode Rules and other rules that might interfere.
  5. Make sure to place this rule before other rules
  6. Deploy the rule

​
Still having issues?

Troubleshooting steps:
  1. Check your hosting provider’s security logs for blocked ModAPI/ requests
  2. Verify your webhook endpoint returns a 200 status code within 5 seconds
  3. Test with a simple endpoint to isolate the issue
  4. Ensure firewall rules don’t conflict with allow rules
Get help: Contact our support team at support@moderationapi.com for assistance with configuration or to allowlist our IP addresses for your specific account.