Webhooks entrantes

Los webhooks entrantes permiten que herramientas externas publiquen mensajes automatizados en un canal de HansaChat. Úselos para actualizaciones de despliegues, alertas de monitorización, notificaciones de tickets, envíos de formularios y otros eventos que deban aparecer en el chat del equipo.

Solo los administradores del espacio de trabajo pueden crear y gestionar webhooks entrantes.

Crear un webhook

1. Abra Configuración desde la barra lateral inferior izquierda.
2. Seleccione Webhooks.
3. Elija Crear webhook.
4. Introduzca un nombre de webhook claro, como CI Deployments.
5. Elija el canal donde deben publicarse los mensajes.
6. Opcionalmente, introduzca una URL de icono.
7. Elija Crear webhook.

Copiar la URL del webhook

Después de la creación, HansaChat muestra la URL del webhook una sola vez. Cópiela y guárdela de forma segura en la herramienta externa que enviará los eventos.

Si cierra esta pantalla sin guardar la URL, rote la URL para generar un nuevo secreto. La URL anterior deja de funcionar inmediatamente después de la rotación.

Gestionar los webhooks

Desde la página de Webhooks, los administradores pueden:

• Editar el nombre del webhook, el canal, la URL del icono o el estado activo.
• Desactivar un webhook para rechazar mensajes nuevos sin eliminarlo.
• Rotar URL para invalidar el secreto anterior y generar una URL nueva.
• Eliminar un webhook. Los mensajes existentes en el chat no se eliminan.

Referencia técnica

Envíe una solicitud POST a la URL del webhook:

https://{workspace-domain}/api/webhooks/{publicID}/{secret}

La URL contiene las credenciales del webhook. No se requiere ninguna cabecera de autenticación adicional. Mantenga la URL completa en secreto.

Solicitud mínima

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Deployment completed successfully"}'

Después de que HansaChat devuelva ok, el mensaje aparece en el canal seleccionado.

Payload compatible con Slack

El endpoint acepta payloads JSON compatibles con Slack con text, blocks y attachments.

{
  "text": "Deployment completed successfully",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Deployment completed"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Branch `main` is now live."
      }
    }
  ]
}

Al menos uno de text, blocks o attachments debe contener texto legible.

Campos admitidos

El tamaño máximo del payload es 1 MB.

Límites de solicitudes

La ingesta de webhooks entrantes está limitada por URL de webhook.

Cada webhook puede aceptar hasta 10 solicitudes autenticadas por minuto y hasta 100 solicitudes autenticadas por hora. Cuando se alcanza cualquiera de los dos límites, HansaChat devuelve 429 resource_exhausted.

Contacte con nosotros si desea aumentar este límite.

Los límites del payload se aplican por separado: el tamaño máximo del cuerpo es 1 MB, blocks admite hasta 50 elementos, attachments admite hasta 100 elementos y el payload debe contener texto legible.

Idempotencia

Añada una cabecera Idempotency-Key cuando su sistema pueda reintentar el mismo evento:

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deploy-1247' \
  -d '{"text":"Deployment #1247 completed"}'

Si HansaChat recibe la misma clave de idempotencia de nuevo para el mismo webhook, devuelve 200 ok sin crear un mensaje duplicado.

Respuestas

Las solicitudes correctas devuelven:

ok

Errores habituales:

Consejos de seguridad

• Trate las URL de webhook como contraseñas.
• Guarde las URL en el gestor de secretos de su herramienta externa.
• Rote la URL si quedó expuesta o se perdió.
• Desactive los webhooks que no use.
• Use un webhook dedicado por sistema externo para poder revocar el acceso de forma limpia.