Webhooks - Documentación de Flexxible

Webhooks és una funcionalitat que permet integrar la plataforma amb eines de tercers per a l’enviament de notificacions quan es produeixen determinats esdeveniments a l’organització. Esdeveniments disponibles:

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

Quan es produeix un d’aquests esdeveniments, la plataforma realitza una crida HTTP a la URL configurada per l’organització i envia un missatge amb la informació corresponent. L’aplicació de destinació 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 d’altres. Aquesta eina només pot ser configurada per un usuari amb rol d’Administrador d’organització.

Vista general

La pantalla principal mostra el llistat de webhooks configurats a l’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 destinació. Adreça del sistema extern que rep l’esdeveniment i actua segons la informació proporcionada al missatge.
Estat. Indica si el webhook està Habilitat o Deshabilitat.

Crear una integració webhook

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

Accedir a Configuració → Integracions Webhook.
Fer clic a Nou.
Emplenar i configurar cada secció del formulari:

Visió general

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

Elements

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

Alerta activada
- Mostra el llistat d’alertes actives de l’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 a cada workspace - Activa el webhook per a totes les operacions per dispositiu.
- Les operacions es poden executar 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 cadascun 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 es produeixi l’esdeveniment. La configuració utilitza format JSON i determina l’estructura i el contingut del missatge transmès al sistema extern. Les variables se substitueixen automàticament per valors reals quan es produeix l’esdeveniment.

Fer clic a Desar.

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 l’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 workspace
#workspace_name	Nom del workspace
#workspace_last_user	Últim usuari que va utilitzar el workspace
#workspace_reporting_group_id	ID del grup d’informe
#workspace_reporting_group_name	Nom del grup d’informe
#workspace_internal_id	Workspace internal ID

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 workspace
#workspace_name	Nom del workspace
#workspace_last_user	Últim usuari que va utilitzar el workspace
#workspace_reporting_group_id	ID del grup d’informe
#workspace_reporting_group_name	Nom del grup d’informe
#operation_startedby	Usuari o component que va iniciar l’execució del microservei
#workspace_internal_id	Workspace internal ID

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 l’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 l’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	Nombre total de workspaces processats
#total_warnings	Nombre total d’execucions amb advertències durant l’operació
#total_errors	Nombre 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 l’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 workspace
#workspace_name	Nom del workspace
#workspace_last_user	Últim usuari que va utilitzar el workspace
#workspace_reporting_group_id	ID del grup d’informe
#workspace_reporting_group_name	Nom del grup d’informe
#workspace_operation_result	Resultat de l’operació al workspace
#workspace_operation_startdate	Data i hora d’inici de l’operació al workspace (ISO 8601)
#workspace_operation_enddate	Data i hora de finalització de l’operació al workspace (ISO 8601)
#workspace_internal_id	Workspace internal ID

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 es pot utilitzar com a base per construir el missatge enviat des de la plataforma:

{
  "text": "*Flexxible microservice was executed*",
  "blocks": [
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Microservei:*\n#microservice_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Resultat:*\n#operation_result"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Organització:*\n#organization_name"
        },
        {
          "type": "mrkdwn",
          "text": "*Workspace:*\n#workspace_name"
        }
      ]
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Inici:*\n#operation_startdate"
        },
        {
          "type": "mrkdwn",
          "text": "*Fi:*\n#operation_enddate"
        }
      ]
    }
  ]
}

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.

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 destinació. Adreça del sistema extern que rep l’esdeveniment i actua segons la informació proporcionada al 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

Intents 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 es poden filtrar segons els criteris següents: Tots els intents, Intents exitosos, Intents pendents, Intents fallits i Intents en progrés. La taula inclou la informació següent:

Estat. Resultat de l’execució.
Durada. En mil·lisegons, temps que va trigar a 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 programació següent:

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)

Cada interval s’inicia a partir de l’error de l’intent anterior.

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

Accions sobre webhooks

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

Habilitar / Deshabilitar

Habilita o deshabilita el webhook segons el seu estat actual.

Els webhooks estan deshabilitats per defecte.

Editar

Permet modificar:

Nom
Tipus d’esdeveniment
URL de destinació
Recursos
Plantilla de missatge

Eliminar

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

Provar

Envia un missatge amb el contingut de la plantilla a la URL configurada sense reemplaçar les variables per valors reals. L’objectiu d’aquesta acció és validar la connectivitat i el format del missatge.

​Vista general

​Crear una integració webhook

​Variables disponibles per al missatge

​Tots els tipus d’esdeveniments

​Alerta activada

​Exemple de plantilla

​Microservei executat

​Exemple de plantilla

​Objecte creat, modificat o eliminat

​Exemple de plantilla

​Operació executada

​Exemple de plantilla

​Operació executada en un workspace

​Exemple de plantilla

​Slack

​Microsoft Teams

​Vista de detall

​Visió general

​1. Visió general

​2. Recursos seleccionats

​3. Plantilla de missatge

​Mètriques

​Intents de lliurament de missatges

​Accions sobre webhooks

​Habilitar / Deshabilitar

​Editar

​Eliminar

​Provar

Vista general

Crear una integració webhook

Variables disponibles per al missatge

Tots els tipus d’esdeveniments

Alerta activada

Exemple de plantilla

Microservei executat

Exemple de plantilla

Objecte creat, modificat o eliminat

Exemple de plantilla

Operació executada

Exemple de plantilla

Operació executada en un workspace

Exemple de plantilla

Slack

Microsoft Teams

Vista de detall

Visió general

1. Visió general

2. Recursos seleccionats

3. Plantilla de missatge

Mètriques

Intents de lliurament de missatges

Accions sobre webhooks

Habilitar / Deshabilitar

Editar

Eliminar

Provar