Webhooks

Webhooks és una funcionalitat que permet integrar Portal amb eines de tercers per a l'enviament de notificacions quan es produeixen determinats esdeveniments a la organització.

Esdeveniments disponibles:

• Alerta activada
• Microservei executat
• Objecte creat
• Objecte modificat
• Objecte eliminat
• Operació executada
• Operació executada en un workspace

Quan ocorre un d'aquests esdeveniments, Portal realitza una crida HTTP a la URL configurada per l'organització i envia un missatge amb la informació corresponent. L'aplicació de destí pot utilitzar aquestes dades per executar accions com crear un tiquet en un sistema ITSM, enviar un missatge per Slack o Microsoft Teams, enviar un correu electrònic, entre altres.

Aquesta eina només pot ser configurada per un usuari amb rol de Administrador d'organització.

Visió general

La pantalla principal mostra el llistat de webhooks configurats a la organització, indicant si estan habilitats o deshabilitats. La taula inclou:

• Nom. Nom assignat al webhook. En fer clic s'accedeix a la seva vista de detall.
• Tipus d'esdeveniment. Esdeveniment que activarà el webhook.
• URL de destí. Adreça del sistema extern que rep l'esdeveniment i actua segons la informació proporcionada en el missatge.
• Estat. Indica si el webhook està Habilitat o Deshabilitat.

Crear una integració webhook

Per crear un nou webhook s'han de seguir els següents passos:

1. En Portal, accedir a Configuració -> Integracions Webhook.

2. Fer clic a Nou.

3. Omplir i configurar cada secció del formulari:

   Visió general

   

   • Nom. Nom assignat al webhook.
   • Tipus d'esdeveniment. Esdeveniment que activarà el webhook.
   • URL de destí. Adreça del sistema extern que rep l'esdeveniment i actua segons la informació proporcionada en el missatge.

   Elements

   

   El contingut d'aquesta taula depèn del tipus d'esdeveniment seleccionat.

   • Alerta activada

     • Mostra el llistat d'alertes actives de la organització per seleccionar quines enviaran el webhook.

     • Enviar webhook per a totes les alertes - Activa el webhook per a totes les alertes.

   • Microservei executat

     • Mostra el llistat de microserveis habilitats per seleccionar quins enviaran el webhook.

     • Enviar webhook per a tots els microserveis - Activa el webhook per a tots els microserveis.

     • En ambdós casos, el botó Veure permet accedir a la vista de detall del recurs.

   • Objecte creat, Objecte modificat o Objecte eliminat

     • Mostren un llistat per seleccionar l'objecte que enviarà el webhook després de l'acció corresponent.

     • Enviar webhook per a tots els objectes - Activa el webhook per a tots els objectes.

   • Operació executada

     • Mostra un llistat per seleccionar l'operació que enviarà el webhook quan s'executi.

     • Enviar webhook per a totes les operacions - Activa el webhook per a totes les operacions.

   • Operació executada en un workspace

     • Mostra un llistat per seleccionar l'operació que enviarà un webhook per cada dispositiu en què s'ha executat.

     • Enviar webhooks per a totes les operacions executades en cada workspace - Activa el webhook per a totes les operacions per dispositiu.

     nota

     • Les operacions poden executar-se en un o més dispositius.

     • L'esdeveniment Operació executada permet enviar un webhook a nivell global.

     • L'esdeveniment Operació executada en un workspace permet enviar un webhook per cada un dels dispositius en què s'ha executat l'operació.

       Exemple:

       Si s'executa l'operació Reiniciar en tres dispositius simultàniament, es generaran:

       • Una notificació webhook de tipus Operació executada.
       • Tres notificacions webhook de tipus Operació executada en un workspace.

   Configuració del missatge

   

   En aquest apartat es defineix el missatge que s'enviarà quan occorri l'esdeveniment. La configuració utilitza format JSON i determina l'estructura i el contingut del missatge transmès al sistema extern.

   Les variables es substitueixen automàticament per valors reals quan es produeix l'esdeveniment.

4. Fer clic a Guardar.

avís

Una organització no hauria de tenir dos webhooks amb la mateixa configuració perquè podria generar enviaments duplicats.

Variables disponibles per al missatge

Tots els tipus d'esdeveniments

Variables	Descripció
#event_type	Tipus d'esdeveniment
#organization_id	ID de l'organització
#organization_name	Nom de la organització/inquilí
#timestamp	Data i hora de l'esdeveniment (ISO 8601)

Alerta activada

Variables	Descripció
#alert_name	Nom de l'alerta
#alert_information	Informació addicional de l'alerta
#alert_start	Data i hora d'inici de l'alerta (ISO 8601)
#alert_element	Element que va disparar l'alerta
#workspace_id	ID del dispositiu
#workspace_name	Nom del dispositiu
#workspace_last_user	Últim usuari que va usar el dispositiu
#workspace_reporting_group_id	ID del grup de report
#workspace_reporting_group_name	Nom del grup de report

Exemple de plantilla

{
    "message": {
        "event_type": "#event_type",
        "organization_id": "#organization_id",
        "organization_name": "#organization_name",
        "workspace_id": "#workspace_id",
        "workspace_name": "#workspace_name",
        "workspace_last_user": "#workspace_last_user",
        "reporting_group_id": "#workspace_reporting_group_id",
        "reporting_group_name": "#workspace_reporting_group_name",
        "alert_name": "#alert_name",
        "alert_information": "#alert_information",
        "alert_start": "#alert_start",
        "alert_element": "#alert_element",
        "timestamp": "#timestamp"
    }
}

Microservei executat

Variables	Descripció
#operation_id	ID de l'operació executada
#microservice_id	ID del microservei
#microservice_name	Nom del microservei
#operation_startdate	Data i hora d'inici de l'operació (ISO 8601)
#operation_enddate	Data i hora de fi de l'operació (ISO 8601)
#operation_result	Resultat de l'operació (Completed, Error, Timeout o Cancelled)
#workspace_id	ID del dispositiu
#workspace_name	Nom del dispositiu
#workspace_last_user	Últim usuari que va usar el dispositiu
#workspace_reporting_group_id	ID del grup de report
#workspace_reporting_group_name	Nom del grup de report

Exemple de plantilla

{
    "message": {
      "event_type" : "#event_type",
      "organization_id" : "#organization_id",
      "organization_name" : "#organization_name",
      "timestamp" : "#timestamp",
      "workspace_id" : "#workspace_id",
      "workspace_name" : "#workspace_name",
      "workspace_last_user" : "#workspace_last_user",
      "reporting_group_id" : "#workspace_reporting_group_id",
      "reporting_group_name" : "#workspace_reporting_group_name",
      "operation_id": "#operation_id",
      "microservice_id": "#microservice_id",
      "microservice_name": "#microservice_name",
      "operation_startdate": "#operation_startdate",
      "operation_enddate": "#operation_enddate",
      "operation_result": "#operation_result"
    }
}

Objecte creat, modificat o eliminat

Variables	Descripció
#event_type	Tipus d'esdeveniment
#organization_id	ID de l'organització
#organization_name	Nom de la organització/inquilí
#timestamp	Data i hora de l'esdeveniment (ISO 8601)
#entity_type	Tipus d'entitat
#entity_name	Nom de l'entitat
#entity_id	ID de l'entitat
#action	Acció realitzada (Creació, Modificació o Eliminació)
#triggered_by_name	Nom de l'usuari que va disparar l'esdeveniment
#triggered_by_email	Adreça de correu electrònic de l'usuari que va disparar l'esdeveniment
#triggered_by_id	ID de l'usuari que va disparar l'esdeveniment

Exemple de plantilla

{
  "message": {
    "event-type": "#event_type",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "entity": {
      "entity-type": "#entity_type",
      "object-name": "#entity_name",
      "object-id": "#entity_id"
    },
    "metadata": {
      "action": "#action",
      "timestamp": "#timestamp",
      "user-name": "#triggered_by_name",
      "useremail": "#triggered_by_email",
      "user-id": "#triggered_by_id"
    }
  }
}

Operació executada

Variables	Descripció
#event_type	Tipus d'esdeveniment
#timestamp	Data i hora de l'esdeveniment (ISO 8601)
#organization_id	ID de l'organització
#organization_name	Nom de la organització/inquilí
#operation_type	Tipus d'operació
#description	Descripció de l'operació
#status	Estat actual de l'execució de l'operació
#summary	Resum de l'operació (JSON)
#started_by	Usuari que va iniciar l'operació
#created_at	Data i hora de creació de l'operació (ISO 8601)
#started_at	Data i hora d'inici de l'operació (ISO 8601)
#finished_at	Data i hora de finalització de l'operació (ISO 8601)
#total_workspaces	Número total de dispositius processats
#total_warnings	Número total d'execucions amb advertències durant l'operació
#total_errors	Número total d'execucions amb errors durant l'operació
#flow_id	ID del flux associat
#microservice_id	ID del microservei associat
#fra_type	Tipus de Flexxible Remote Assistance (FRA)
#fra_start	Data i hora d'inici de Flexxible Remote Assistance (FRA) (ISO 8601)
#fra_end	Data i hora de fi de Flexxible Remote Assistance (FRA) (ISO 8601)

Exemple de plantilla

{
  "message": {
    "event_type": "#event_type",
    "timestamp": "#timestamp",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "operation": {
      "type": "#operation_type",
      "description": "#description",
      "status": "#status",
      "summary": "#summary",
      "started_by": "#started_by",
      "created_at": "#created_at",
      "started_at": "#started_at",
      "finished_at": "#finished_at"
    },
    "results": {
      "total_workspaces": "#total_workspaces",
      "total_warnings": "#total_warnings",
      "total_errors": "#total_errors"
    },
    "context": {
      "flow_id": "#flow_id",
      "microservice_id": "#microservice_id",
      "fra_type": "#fra_type",
      "fra_start": "#fra_start",
      "fra_end": "#fra_end"
    }
  }
}

Operació executada en un workspace

Variables	Descripció
#event_type	Tipus d'esdeveniment
#timestamp	Data i hora de l'esdeveniment (ISO 8601)
#organization_id	ID de l'organització
#organization_name	Nom de la organització/inquilí
#operation_type	Tipus d'operació
#description	Descripció de l'operació
#operation_status	Estat de l'operació
#started_by	Usuari que va iniciar l'operació
#created_at	Data i hora de creació de l'operació (ISO 8601)
#started_at	Data i hora d'inici de l'operació (ISO 8601)
#finished_at	Data i hora de fi de l'operació (ISO 8601)
#operation_flow_id	ID del flux associat a l'operació
#operation_microservice_id	ID del microservei associat a l'operació
#operation_fra_type	Tipus de Flexxible Remote Assistance (FRA)
#operation_fra_start	Data i hora d'inici de Flexxible Remote Assistance (FRA)(ISO 8601)
#operation_fra_end	Data i hora de fi de Flexxible Remote Assistance (FRA) (ISO 8601)
#workspace_id	ID del dispositiu
#workspace_name	Nom del dispositiu
#workspace_last_user	Últim usuari que va usar el dispositiu
#workspace_reporting_group_id	ID del grup de report
#workspace_reporting_group_name	Nom del grup de report
#workspace_operation_result	Resultat de l'operació en el dispositiu
#workspace_operation_startdate	Data i hora d'inici de l'operació en el workspace (ISO 8601)
#workspace_operation_enddate	Data i hora de finalització de l'operació en el workspace (ISO 8601)

Exemple de plantilla

{
  "message": {
    "event_type": "#event_type",
    "timestamp": "#timestamp",
    "organization": {
      "id": "#organization_id",
      "name": "#organization_name"
    },
    "operation": {
      "type": "#operation_type",
      "description": "#description",
      "status": "#operation_status",
      "started_by": "#started_by",
      "created_at": "#created_at",
      "started_at": "#started_at",
      "finished_at": "#finished_at"
    },
    "context": {
      "flow_id": "#operation_flow_id",
      "microservice_id": "#operation_microservice_id",
      "fra_type": "#operation_fra_type",
      "fra_start": "#operation_fra_start",
      "fra_end": "#operation_fra_end"
    },
    "workspace": {
      "id": "#workspace_id",
      "name": "#workspace_name",
      "last_user": "#workspace_last_user",
      "reporting_group": {
        "id": "#workspace_reporting_group_id",
        "name": "#workspace_reporting_group_name"
      }
    },
    "execution": {
      "result": "#workspace_operation_result",
      "start_date": "#workspace_operation_startdate",
      "end_date": "#workspace_operation_enddate"
    }
  }
}

Slack

A continuació, es mostra un exemple de plantilla compatible amb Slack Incoming Webhooks, que pot utilitzar-se com a base per construir el missatge enviat des de Portal:

{
  "text": "*Flexxible microservice was executed*",
  "blocks": [
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Microservicio:*\n#microservice_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Resultado:*\n#operation_result"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Organización:*\n#organization_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Workspace:*\n#workspace_name"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Inicio:*\n#operation_startdate"
        },
        {
          "type": "mrkdwn",
          "text": "*Fin:*\n#operation_enddate"
        }
      ]
    }
  ]
}

nota

Per a més informació sobre el format de missatges, els blocs disponibles i les millors pràctiques, consulta la guia oficial de Slack.

Microsoft Teams

A Microsoft Teams, les plantilles es poden consultar directament des de la configuració de cada canal.

nota

Per obtenir detalls sobre com configurar correctament un webhook entrant i quina estructura ha de tenir la plantilla JSON, consulta la guia oficial de Microsoft.

Vista de detall

En seleccionar un webhook des de la taula s'accedeix a la seva vista de detall:

• Visió general
• Mètriques

Visió general

Presenta targetes amb informació bàsica: Estat, Creat el i Actualitzat el.

1. Visió general

• Nom. Nom assignat al webhook.
• Tipus d'esdeveniment. Esdeveniment que activarà el webhook.
• Creat per. Usuari que va crear l'esdeveniment.
• Actualitzat per. Últim usuari que va modificar el webhook.
• URL de destí. Adreça del sistema extern que rep l'esdeveniment i actua segons la informació proporcionada en el missatge.

2. Recursos seleccionats

Mostra els recursos associats segons el tipus d'esdeveniment.

3. Plantilla de missatge

Presenta l'estructura JSON configurada per al webhook.

Mètriques

Intentos de lliurament de missatges

Aquesta pestanya presenta dos nivells d'informació. A la part superior, es mostren targetes resum amb l'estat global dels missatges enviats mitjançant el webhook:

• Missatges exitosos
• Missatges pendents
• Missatges en progrés
• Missatges fallits
• Total de missatges
• Índex d'èxit

A la part inferior es mostra una taula amb l'històric d'intents d'enviament de missatges corresponents als últims 28 dies. Els registres poden filtrar-se segons els següents criteris: Tots els intents, Intents exitosos, Intents pendents, Intents fallits i Intents en progrés.

La taula inclou la següent informació:

• Estat. Resultat de l'execució.
• Durada. En mil·lisegons, temps que va trigar en executar-se el webhook.
• Codi de resposta. Codi HTTP retornat en executar-se el webhook.
• Executat el. Data i hora en què es va realitzar l'execució.
• Accions. Obre una finestra amb el detall de l'execució.

Quan una crida a la URL de destinació no es completa correctament, el sistema reintenta l'enviament del missatge de forma automàtica, segons la següent programació:

• Immediatament
• Als 5 segons
• Als 5 minuts
• Als 30 minuts
• A les 2 hores
• A les 5 hores
• A les 10 hores
• A les 10 hores (addicionals)

nota

Cada interval s'inicia a partir del fall de l'intent anterior.

info

Si l'enviament d'un missatge falla tres vegades i es completa amb èxit en el quart intent, a la taula es mostraran quatre intents (tres fallits i un exitós). No obstant, el sistema el comptabilitzarà com un únic missatge.

Accions sobre webhooks

La vista de detall també permet realitzar les següents accions sobre el webhook:

Habilitar / Deshabilitar

Habilita o deshabilita el webhook segons el seu estat actual.

nota

Els webhooks estan deshabilitats per defecte.

Edita

Permet modificar:

• Nom
• Tipus d'esdeveniment
• URL de destinació
• Recursos
• Plantilla de missatge

Suprimeix

Elimina el webhook de forma permanent. Aquesta operació no es pot desfer.

Provar

Envia un missatge amb el contingut de la plantilla a la URL configurada sense substituir les variables per valors reals. L'objectiu d'aquesta accion és validar la connectivitat i el format del missatge.