Webhooks

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": "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,
});

import { buffer } from "micro";

const handler = async (req, res) => {
  const webhookRawBody = await buffer(req);
  const webhookSignatureHeader = req.headers["modapi-signature"];

  const payload = await moderationApi.webhooks.constructEvent(
    webhookRawBody,
    webhookSignatureHeader,
    process.env.MODAPI_WEBHOOK_SECRET
  );
};

// disable body parser so we can access raw body
export const config = {
  api: {
    bodyParser: false,
  },
};

export default handler;

​

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.