API y webhooks
Para quien quiera conectar Silkward con su web, un bot propio o una hoja de cálculo. Las claves y los webhooks se crean en el panel del servidor, en API (solo el propietario y los administradores).
Autenticación
Cada clave pertenece a un servidor y empieza por swk_. Envíala en la cabecera Authorization. La API es de solo lectura; guarda la clave en tu servidor, nunca en código que se ejecute en el navegador.
curl http://192.168.0.240:3300/api/v1/cases?limit=5 \ -H "Authorization: Bearer swk_tu_clave"
Límite: 60 peticiones por minuto (300 con Gold). Las respuestas llevan X-RateLimit-Limit y X-RateLimit-Remaining; al pasarte recibes 429 con Retry-After.
Rutas
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/v1/guild | Plan del servidor y módulos activos. |
| GET | /api/v1/cases?user=&limit=&before= | Casos de moderación, del más reciente al más antiguo. |
| GET | /api/v1/cases/{número} | Un caso. |
| GET | /api/v1/tickets?status=open|closed&limit=&before= | Tickets (sin el contenido de los mensajes). |
| GET | /api/v1/suggestions?status=&limit=&before= | Sugerencias con sus votos. |
| GET | /api/v1/levels?limit= | Clasificación de niveles. |
| GET | /api/v1/levels/{userId} | Nivel de un miembro. |
Las listas devuelven como mucho 100 elementos (limit, 25 por defecto). Para ver más, pasa en before el número del último que recibiste. Los IDs de Discord van siempre como texto.
Webhooks
Silkward hace un POST con JSON a tu URL (solo https) cuando ocurre un evento al que te hayas suscrito. Responde con un código 2xx en menos de 8 segundos; si no, se reintenta a los 1, 5 y 30 minutos, a las 2 y a las 6 horas. Tras 20 fallos seguidos el webhook se desactiva y lo verás en el panel.
POST /webhook
X-Silkward-Event: case.created
X-Silkward-Delivery: 2b9c… (identificador único: úsalo para ignorar repetidos)
X-Silkward-Signature: t=1767225600,v1=5f2a…
{
"event": "case.created",
"guildId": "123456789012345678",
"createdAt": "2026-01-01T00:00:00.000Z",
"data": { "number": 42, "type": "warn", "targetId": "…", "moderatorId": "…", "reason": "Spam" }
}| Evento | Cuándo | Campos de data |
|---|---|---|
| case.created | Se crea un caso de moderación | number, type, targetId, moderatorId, reason, durationSeconds, source |
| ticket.opened | Alguien abre un ticket | number, categoryId, category, openerId, threadId |
| ticket.closed | Se cierra un ticket | number, categoryId, openerId, closedBy, reason, threadId |
| form.submitted | Llega una respuesta a un formulario | formId, form, submissionId, userId, answers |
| suggestion.created | Se publica una sugerencia | number, authorId, content |
| level.up | Un miembro sube de nivel | userId, level, previousLevel |
El botón «Probar» del panel envía un evento ping con data vacío.
Comprobar la firma
Calcula el HMAC-SHA256 de <t>.<cuerpo en bruto> con el secreto del webhook (whsec_…) y compáralo con v1. Rechaza las peticiones con más de 5 minutos para evitar repeticiones. Ejemplo en Node.js:
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
const got = Buffer.from(v1, "hex");
return got.length === expected.length && timingSafeEqual(got, expected);
}