Webhook

1 Como eles funcionam?
2 Quando usar webhooks?
- 2.1 Para realizar atualizações rápidas
3 Como fazer a implementação do webhook?
4 Exemplo de payload de um webhook

Webhook é uma tecnologia utilizada para permitir a comunicação entre duas aplicações e enviar notificações quase em tempo real. O envio ou o recebimento de dados é disparado quando determinado evento acontecer em uma das aplicações.

Por exemplo, se você já recebeu alguma notificação no celular sobre a alteração do status de um pedido, ou quando fez um pagamento com seu cartão de crédito, você recebeu a ação de um webhook.

Como eles funcionam?

Agora, vamos à parte técnica para verificar como tudo isso acontece na prática. Como mencionamos, o webhook permite a comunicação entre dois sistemas. Para isso, ele precisa de um endpoint, que é uma URL que funciona como um serviço de recepção para atender aos eventos que chegam.

Os eventos representam alguma mudança em uma condição inicial de um dado. Portanto, a mudança no status de pendente para aprovado é considerada um evento, e podemos utilizar um webhook para promover a comunicação entre as aplicações.

Além de disponibilizar a URL, precisamos informar ao sistema provedor qual será o gatilho para o envio do webhook, ou seja, em que momento será feito o disparo para a comunicação entre os dois sistemas.

Os dados recebidos em um webhook podem ser no formato JSON, XML ou como dados de formulário (application/x-www-form-urlencoded ou multipart/form-data).

Vale ressaltar que o formato mais utilizado é o JSON. É importante dizer que o webhook tanto pode receber quanto enviar dados, e ele pode ser utilizado para algumas funções específicas, como:

push: para enviar notificações em tempo real em aplicações web;
pipes: para permitir a integração entre aplicações por meio do processamento dos dados recebidos ou enviados pelo webhook;
plugins: para o desenvolvimento de plugins para adicionar funcionalidades em aplicações web, como a integração entre sistemas e o envio de notificações.

Quando usar webhooks?

Apesar de ser um facilitador para a comunicação entre duas aplicações, nem sempre a utilização de webhooks é a escolha ideal. Portanto, confira algumas situações em que esse recurso representa uma boa alternativa.

Para realizar atualizações rápidas

Os webhooks são uma excelente alternativa quando precisamos realizar pequenas atualizações quase em tempo real. As notificações de pagamento quando utilizamos os cartões bancários são um bom exemplo da importância desse recurso.

Ele permite notificar o cliente sempre que uma transação for realizada. Dessa forma, a pessoa consegue identificar movimentações indevidas e pode tomar uma ação imediata para evitar maiores prejuízos.

Como fazer a implementação do webhook?

1 - Crie a sua API para recebimentos de Webhooks

2 - Vincule a sua API na central de hooks

3- Cadastre seu hook

4 - Vincule seu hook a uma action (ação) da ocorrência desejada.

Exemplo de payload de um webhook

{
  "request": {
    "id": "64c3fd0e174048da23bbfced"
  },
  "funcionalidade": {
    "id": 50,
    "descricao": "Solicitação de cartão"
  },
  "ocorrencia": {
    "protocolo": "665544120230728090008",
    "dataRegistro": "2023-07-28T17:38:22.353Z",
    "dataAtualizacao": "2023-07-28T17:38:22.353Z",
    "dataVencimentoSla": "1970-01-01T00:00:00.000Z",
    "tipoOcorrencia": {
      "id": 401,
      "descricao": "Solicitação de segunda via"
    },
    "assunto": {
      "id": 280,
      "descricao": "Segunda via de cartão"
    },
    "solicitante": {
      "chaveUnica": "99999999999",
      "numeroContrato": "00000000001",
      "integracao": "implementação futura"
    },
    "beneficiario": {
      "chaveUnica": "99999999999",
      "numeroContrato": "00000000001",
      "integracao": "implementação futura"
    },
    "canal": {
      "id": "implementação futura",
      "descricao": "implementação futura"
    },
    "naturezaAtendimento": {
      "id": "implementação futura",
      "descricao": "implementação futura"
    },
    "solicitacao": {
      "template": {
        "id": null,
        "descricao": null
      },
      "formularios": [
        {
          "nome": "Motivo da solicitação",
          "idForm": "6474de4f99b0444741a15c6e",
          "itens": [
            {
              "motivoDaSolicitacao": {
                "label": "Cartão danificado",
                "value": "Cartão danificado"
              }
            }
          ]
        },
        {
          "nome": "Complemento",
          "idForm": "6474ce8099b0444741a15a8c",
          "itens": [
            {
              "formaDeEntrega": {
                "label": "Retirada na Operadora",
                "value": "Retirada na Operadora"
              },
              "retiradaNaOperadora": "O cartão deve ser retirado em nossa Operadora. Endereço...",
              "cep": "29010935",
              "logradouro": "Ed. Trade Center Avenida Jerônimo Monteiro",
              "numero": "1000",
              "complemento": "SALA 414, 416 e 419",
              "bairro": "CENTRO"
            }
          ]
        }
      ]
    },
    "atendimento": {
      "atendente": {
        "id": null,
        "nome": null,
        "email": null
      },
      "status": {
        "id": 888,
        "descricao": "Solicitado",
        "dataAtribuicao": "implementação futura"
      },
      "anotacoes": [
        {
          "texto": "Ocorrência criada em 28/07/2023 com status Solicitado.",
          "dataHora": "2023-07-28T17:38:22.607Z",
          "ordem": "",
          "atendente": {
            "id": null,
            "nome": null,
            "email": null
          },
          "visibilidade": "externa"
        }
      ],
      "encerramento": {}
    }
  },
  "instancia_aplicacao": 1 (1 == Sandbox || 2 == Produção)
}

ATENÇÃO

Caso algum componente do formulário não for preenchido, o atributo não será enviado via webhook, no caso acima não sendo informados os componentes "numero” e “complemento” o formulário seria enviado desta forma.

{
  ...
  
      "formularios": [
        {
          "nome": "Motivo da solicitação",
          "idForm": "6474de4f99b0444741a15c6e",
          "itens": [
            {
              "motivoDaSolicitacao": {
                "label": "Cartão danificado",
                "value": "Cartão danificado"
              }
            }
          ]
        },
        {
          "nome": "Complemento",
          "idForm": "6474ce8099b0444741a15a8c",
          "itens": [
            {
              "formaDeEntrega": {
                "label": "Retirada na Operadora",
                "value": "Retirada na Operadora"
              },
              "retiradaNaOperadora": "O cartão deve ser retirado em nossa Operadora. Endereço...",
              "cep": "29010935",
              "bairro": "CENTRO"
            }
          ]
        }
      ]
    }
    
   ...
}

A partir de agora a ocorrência está parametrizada para o status desejado enviar um webhook para API desejada.

Obrigado e até a próxima.