Webhooks entrantes | HansaChat Docs

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.

Abrir Webhooks desde Configuración

Crear un webhook

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

Página de webhooks vacía

Formulario de 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.

URL del webhook mostrada una sola vez

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.

Mensaje de prueba del webhook en un canal

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

Campo	Obligatorio	Notas
`text`	No	Contenido del mensaje en texto plano.
`blocks`	No	Bloques al estilo de Slack Block Kit. Hasta 50 bloques. Tipos de bloque admitidos: `section`, `header`, `context`, `image`.
`attachments`	No	Adjuntos al estilo de Slack. Hasta 100 adjuntos.

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:

Estado	Cuerpo	Significado
400	`invalid_payload`	El cuerpo JSON no se pudo analizar.
400	`invalid_blocks`	La solicitud contiene más de 50 bloques.
400	`too_many_attachments`	La solicitud contiene más de 100 adjuntos.
400	`no_text`	El payload no tiene texto legible.
429	`resource_exhausted`	El webhook superó 10 solicitudes por minuto o 100 solicitudes por hora.
404	`no_active_hooks`	El espacio de trabajo, el webhook, el secreto o el estado activo no son válidos.
410	`channel_is_archived`	El canal de destino está archivado.
503	`temporarily_unavailable`	HansaChat no puede procesar el mensaje ahora mismo. Reintente más tarde con la misma `Idempotency-Key`.

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.