Webhooks
Webhook events
Technical specification for Iffy webhook events
Request format
- Method: POST
- Headers:
Content-Type: application/json
X-Signature: HMAC SHA256 signature
Events and payloads
record.flagged
{
"id": "string", // Moderation ID
"event": "record.flagged",
"payload": {
"id": "string", // Record ID
"clientId": "string", // Your unique record Id
"clientUrl": "string" | undefined, // Your unique record URL
"name": "string",
"entity": "string", // Entity (e.g., post, comment)
"metadata": {
["string"]: "string" // Your custom metadata
},
"status": "Compliant" | "Flagged" | undefined,
"statusUpdatedAt": "string" | undefined, // Date of moderation
"statusUpdatedVia": "Manual", "Automation", "AI",
"user": {
"id": "string", // User ID
"clientId": "string", // Your unique user Id
"clientUrl": "string" | undefined, // Your unique user URL
"protected": boolean,
"metadata": {
["string"]: "string" // Your custom metadata
},
"status": "Compliant" | "Suspended" | "Banned" | undefined,
"statusUpdatedAt": "string" | undefined, // Date of user action
"statusUpdatedVia": "Manual", "Automation", "AI"
}
},
"timestamp": "string" // Unix timestamp in milliseconds
}
record.unflagged
{
"id": "string", // Moderation ID
"event": "record.unflagged",
"payload": {
"id": "string", // Record ID
"clientId": "string", // Your unique record identifier
"clientUrl": "string" | undefined, // Your unique record URL
"name": "string",
"entity": "string", // Entity (e.g., post, comment)
"metadata": {
["string"]: "string" // Your custom metadata
},
"status": "Compliant" | "Flagged" | undefined,
"statusUpdatedAt": "string" | undefined, // Date of moderation
"statusUpdatedVia": "Manual", "Automation", "AI",
"user": {
"id": "string", // User ID
"clientId": "string", // Your unique user Id
"clientUrl": "string" | undefined, // Your unique user URL
"protected": boolean,
"metadata": {
["string"]: "string" // Your custom metadata
},
"status": "Compliant" | "Suspended" | "Banned" | undefined,
"statusUpdatedAt": "string" | undefined, // Date of user action
"statusUpdatedVia": "Manual", "Automation", "AI"
}
},
"timestamp": "string"
}
user.suspended
{
"id": "string", // User action ID
"event": "user.suspended",
"payload": {
"id": "string", // User ID
"clientId": "string", // Your unique record identifier
"clientUrl": "string" | undefined, // Your unique record URL
"protected": boolean,
"metadata": {
["string"]: "string" // Your custom metadata
},
"status": "Compliant" | "Suspended" | "Banned" | undefined,
"statusUpdatedAt": "string" | undefined, // Date of user action
"statusUpdatedVia": "Manual", "Automation", "AI"
},
"timestamp": "string"
}
user.compliant
{
"id": "string", // User action ID
"event": "user.compliant",
"payload": {
"id": "string", // User ID
"clientId": "string", // Your unique record identifier
"clientUrl": "string" | undefined, // Your unique record URL
"protected": boolean,
"metadata": {
["string"]: "string" // Your custom metadata
},
"status": "Compliant" | "Suspended" | "Banned" | undefined,
"statusUpdatedAt": "string" | undefined, // Date of user action
"statusUpdatedVia": "Manual", "Automation", "AI"
},
"timestamp": "string"
}
user.banned
{
"id": "string", // User action ID
"event": "user.banned",
"payload": {
"id": "string", // User ID
"clientId": "string", // Your unique record identifier
"clientUrl": "string" | undefined, // Your unique record URL
"protected": boolean,
"metadata": {
["string"]: "string" // Your custom metadata
},
"status": "Compliant" | "Suspended" | "Banned" | undefined,
"statusUpdatedAt": "string" | undefined, // Date of user action
"statusUpdatedVia": "Manual", "Automation", "AI"
},
"timestamp": "string"
}
Security
Signature verification
Verify the X-Signature header using HMAC SHA256:
import crypto from "node:crypto";
const body = JSON.stringify(req.body);
const signature = req.headers["x-signature"];
const secret = process.env.IFFY_WEBHOOK_SECRET;
const hash = crypto.createHmac("sha256", secret).update(body).digest("hex");
if (hash !== signature) {
return res.status(401).send("Invalid signature");
}
Retry logic
We do not currently retry webhooks.