¿Qué es un webhook?
Un webhook es una forma de que InstaSwift "llame" a tu servidor cuando ocurre un evento. En lugar de que tú hagas peticiones a la API para preguntar "¿hay algo nuevo?", InstaSwift te avisa activamente enviando un HTTP POST a tu URL cuando detecta un post nuevo.
Casos de uso
- Guardar posts en tu base de datos: Cada nuevo post de Instagram queda archivado en tu sistema además de publicarse en Discord.
- Notificaciones personalizadas: Envía alertas a tu aplicación móvil, Slack, email, etc.
- Automatizaciones: Conecta con Make, Zapier o n8n para desencadenar flujos de trabajo cuando llega contenido nuevo.
- Mostrar contenido en tu web: Actualiza en tiempo real una sección de tu web con el último contenido de Instagram.
- Moderación personalizada: Analiza el contenido antes de publicarlo o añade lógica de negocio propia.
Configurar la URL del webhook
- Accede al dashboard
Panel de Control > selecciona tu servidor > pestaña "API y Webhooks".
- Añade tu URL
En el campo "URL del webhook", escribe la URL de tu servidor que recibirá las notificaciones. Debe ser accesible públicamente por HTTPS.
- Elige los eventos
Selecciona qué tipos de eventos quieres recibir: nuevo post, nuevo reel, nueva story.
- Guarda y prueba
Haz clic en "Guardar" y luego en "Enviar evento de prueba" para verificar que tu servidor recibe correctamente los eventos.
Formato del payload JSON
Cuando InstaSwift detecta un nuevo post, envía un HTTP POST a tu URL con el siguiente cuerpo JSON:
{
"id": "abc123xyz",
"tipo": "post",
"cuenta": "natgeo",
"caption": "La increíble biodiversidad del Amazonas...",
"mediaUrl": "https://cdn.instagram.com/...",
"postUrl": "https://www.instagram.com/p/xyz/",
"timestamp": "2026-05-25T14:30:00Z",
"feedId": 7,
"guildId": "123456789"
}| Campo | Tipo | Descripción |
|---|---|---|
id | string | ID único del post en Instagram |
tipo | string | "post", "reel" o "story" |
cuenta | string | Nombre de usuario de Instagram |
caption | string | null | Texto del post (puede ser null) |
mediaUrl | string | URL de la imagen o thumbnail |
postUrl | string | URL directa al post en Instagram |
timestamp | string (ISO 8601) | Fecha y hora de publicación en Instagram |
feedId | number | ID del feed que detectó el post |
guildId | string | ID del servidor de Discord |
Verificar la firma HMAC
Para garantizar que las notificaciones que recibes provienen realmente de InstaSwift y no de terceros, cada webhook incluye una cabecera X-InstaSwift-Signature con la firma HMAC-SHA256 del cuerpo del request.
Para verificarla en Node.js:
const crypto = require('crypto');
const secret = 'TU_WEBHOOK_SECRET'; // Del dashboard
const signature = req.headers['x-instaswift-signature'];
const expected = crypto
.createHmac('sha256', secret)
.update(req.rawBody)
.digest('hex');
if (signature !== expected) {
return res.status(401).send('Firma inválida');
}Reintentos en caso de error
Si tu servidor no responde con un código HTTP 2xx (200-299) en el plazo de 10 segundos, InstaSwift considera que la entrega falló y la reintenta:
- 1er reintento: 1 minuto después
- 2do reintento: 5 minutos después
- 3er reintento: 30 minutos después
Si después de tres reintentos el webhook sigue fallando, el evento se descarta y se registra en el log de errores del dashboard.