Webhooks

Los webhooks salientes le permiten recibir notificaciones HTTP POST en tiempo real cuando ocurren eventos en su proyecto. Pro

Descripción general

Los webhooks envían un payload JSON a cualquier endpoint HTTPS que configure cuando ocurre un evento específico en su proyecto. Cada webhook puede suscribirse a uno o más de los siguientes eventos:

Los webhooks están configurados por proyecto individual. Cada proyecto tiene su propio conjunto de endpoints de webhooks con configuraciones y secretos de firma independientes.

Configurar un webhook

1. Vaya a la página de Integraciones de su proyecto
2. Desplácese hasta la sección Webhooks salientes
3. Haga clic en Agregar webhook
4. Ingrese la URL de su endpoint (debe ser HTTPS en producción)
5. Seleccione a qué eventos desea suscribirse
6. Haga clic en Guardar

Después de guardar, se muestra una vez un secreto de firma. Cópie-lo inmediatamente — no se puede recuperar más tarde. Puede regenerarlo en cualquier momento desde el menú de acciones del webhook.

Verificar firmas de webhooks

Cada entrega de webhook incluye un header X-SupDesk-Signature que contiene una firma HMAC-SHA256 del cuerpo de la solicitud. Para verificar un webhook:

1. Calcule HMAC-SHA256(secreto_de_firma, cuerpo_raw_de_la_solicitud)
2. Compare el resultado con el valor hexadecimal en el header X-SupDesk-Signature (después del prefijo sha256=)
3. Use una comparación de tiempo constante para prevenir ataques de temporización

Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyWebhook(secret, body, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

Probar un webhook

Haga clic en el botón Probar junto a un webhook para enviar un payload de ejemplo a su endpoint. El payload de prueba tiene "event": "test" y un campo data.message. Use una herramienta como webhook.site  para inspeccionar la solicitud entregada.

Registro de entregas

El registro de entregas muestra los últimos 50 intentos de entrega para cada webhook, incluyendo:

• Evento — qué evento fue entregado
• Estado — success o failed
• Código de respuesta — código de estado HTTP del endpoint
• Intentos — número de intentos de entrega (incluyendo reintentos)
• Hora — cuándo se intentó la entrega

Comportamiento de reintentos

Cuando una entrega de webhook falla (respuesta 5xx o timeout de red), SupDesk reintenta hasta 3 veces con backoff exponencial:

Los errores de cliente (4xx) no se reintean — indican un problema permanente con la configuración del endpoint.

Requisitos de plan

Los webhooks salientes están disponibles en los planes Pro y Team.