Saltar al contenido
Silkward

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étodoRutaDescripción
GET/api/v1/guildPlan 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" }
}
EventoCuándoCampos de data
case.createdSe crea un caso de moderaciónnumber, type, targetId, moderatorId, reason, durationSeconds, source
ticket.openedAlguien abre un ticketnumber, categoryId, category, openerId, threadId
ticket.closedSe cierra un ticketnumber, categoryId, openerId, closedBy, reason, threadId
form.submittedLlega una respuesta a un formularioformId, form, submissionId, userId, answers
suggestion.createdSe publica una sugerencianumber, authorId, content
level.upUn miembro sube de niveluserId, 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);
}