Introdução

Neste artigo você verá como utilizar os Webhooks na integração de sistemas com o Produttivo. Atualmente essa funcionalidade está em fase beta e é habilitada através de uma solicitação. Algumas revisões poderão ocorrer nesse período e qualquer alteração será comunicada.

Configuração do Webhook

Para configurarmos o webhook, precisaremos das informações abaixo que poderão ser enviadas para a pessoa responsável pelo projeto do Produttivo. Em futuras versões do Produttivo, essa configuração poderá ser realizada diretamente na tela de configuração de integração do sistema.

Subscription URL:

URL a ser chamada

Topic:

Tipo de notificação que estará sendo aguardada. Para essa integração, iremos utilizar:

“work.finished” ou “work.reviewed”: Para receber notificação quando um atividade é finalizada ou revisada
“export_request.available”: Para receber uma notificação quando a exportação PDF for concluída.

HTTP Auth Username (opcional):

Username para autenticação padrão HTTP.

HTTP Auth Password (opcional):

Senha para autenticação padrão HTTP.

Secret key (opcional):

Chave utilizada para assinatura da notificação (ver tópico “Assinatura da notificação”)

Objeto da notificação

O objeto que será enviado contém os seguintes campos:

Atributo	Tipo	Descrição
topic	string	Tipo da notificação (ex.: “work.finished”, “export_request.available”)
uuid	string	Identificador único da notificação
account_id	integer	Identificador da conta no Produttivo
created_at	timestamp	Data e hora de criação da notificação
delivery_attempts	integer	Número de tentativas de envio da notificação
first_sent_at	timestamp	Data e hora da primeira tentativa de envio da notificação
data	object	Dados associados com a notificação (ex.: Work ou ExportRequest)

O conteúdo completo do atributo “data” é o mesmo dos endpoints de consulta da presentes na documentação da API (ex.: /works/{id}).

Abaixo está um exemplo para uma atividade que foi finalizada:

{
  "topic": “work.finished”,
  "uuid": "109f8aca-29e8-4c83-974b-4d360afb47b3",
  "account_id": 123123,
  "created_at": “2021-09-09T23:23:44.000-03:00”,
  "delivery_attempts": 1,
  "first_sent_at": “2021-09-09T23:23:44.000-03:00”,
  "data": {
      "id": 2,
      "work_number": 1,
      "title": "Título da atividade",
      "uuid": "eafd506c-1cf7-4cbe-812f-2bd3bfd40d7f",
      "work_type": "fill_form",
      "form_id": 7,
      "start_time": null,
      "end_time": null,
      "status": "finished",
      "account_id": 11,
      "project_id": 3,
      "details": null,
      "resource_place_id": 10
  }
}

E abaixo um exemplo para exportação concluída:

{
  "topic": “export_request.available”,
  "uuid": "109f8aca-29e8-4c83-974b-4d360afb47b3",
  "account_id": 123123,
  "created_at": “2021-09-09T23:23:44.000-03:00”,
  "delivery_attempts": 1,
  "first_sent_at": “2021-09-09T23:23:44.000-03:00”,
  "data": {
      "id": 3787645,
      "account_id": 60812,
      "status": "available",
      "image_type": "embedded",
      "send_method": "download"
  }
}

Tratando as notificações por Webhook

O código retornado pela requisição do webhook determina o estado da notificação, seja sucesso ou falha. Também existe um tempo limite para a resposta da notificação.

Veja abaixo a os códigos de resposta:

Response code	Descrição	Ação
2xx	Success	Consideramos que o webhook foi enviado com sucesso.
410	Gone	Quando um 410 é recebido, nós consideramos que o recurso não está mais disponível e iremos desativar a inscrição e nenhuma notificação será enviada mais.
429	Too many requests	Quando um 429 é recebido, nós iremos cancelar por um período de minutos ou horas o envio de notificações.
4xx (exceto 410 e 429) ou 5xx	Client or service errors	Tentaremos enviar novamente após 1 minuto. Se a segunda tentativa falhar, definiremos o envio da notificação como falha.

Timeout: O tempo de resposta da requisição não deve ultrapassar 10 segundos. Se esse limite de tempo for atingido, tentaremos enviar apenas mais uma vez após um minuto.

Assinatura da notificação

Para que você possa garantir que uma notificação foi realmente enviada pelo Produttivo, na requisição HTTP nós enviaremos um atributo no cabeçalho chamado X-Hub-Signature. O valor desse atributo será calculado através da criação de uma assinatura do corpo da requisição JSON e o valor da Secret key. Essa assinatura é uma representação hexadecimal (40-byte) de uma assinatura SHA-1 processada utilizando o algoritmo HMAC como definido em RFC2104. O valor do atributo X-Hub-Signature inicia com a string sha1=.

Abaixo está um exemplo da requisição HTTP completa:

POST https://example.org/hooks
User-Agent: produttivo_webhook_system/1.0
X-Hub-Signature: sha1=21ff2e149e0fdcac6f947740f6177f6434bda921
Accept: application/json
Content-Type: application/json

{
  "topic": “work.finished”,
  "uuid": "109f8aca-29e8-4c83-974b-4d360afb47b3",
  "account_id": 123123,
  "created_at": “2021-09-09T23:23:44.000-03:00”,
  "delivery_attempts": 1,
  "first_sent_at": “2021-09-09T23:23:44.000-03:00”,
  "data": {
      "id": 2,
      "work_number": 1,
      "title": "Título da atividade",
      "uuid": "eafd506c-1cf7-4cbe-812f-2bd3bfd40d7f",
      "work_type": "fill_form",
      "form_id": 7,
      "start_time": null,
      "end_time": null,
      "status": "finished",
      "account_id": 11,
      "project_id": 3,
      "details": null,
      "resource_place_id": 10
  }
}

Autenticação (opcional)

Opcionalmente, o webhook poderá ser configurado para enviar um token de autenticação em cada requisição. Para essa integração, será utilizado o padrão OAuth enviando o token no cabeçalho. Abaixo está o exemplo de uma chamada enviando o token no header da requisição:

POST https://example.org/hooks
User-Agent: example/1.0
X-Hub-Signature: sha1=21ff2e149e0fdcac6f947740f6177f6434bda921
Accept: application/json
Content-Type: application/json
Authorization: Barrier cf264696-9c29-11ed-a8fc-0242ac120002

A solicitação do token ocorrerá nos seguintes casos:

Na primeira notificação do webhook
Quando a notificação retornar o status code 401 (não autenticado)

Para essa solicitação, será enviando um parâmetro de Client ID e outro de Client Secret. Abaixo está um exemplo de solicitação do token:

POST https://example.org/getToken
User-Agent: produttivo_webhook_system/1.0
Content-Type: application/x-www-form-urlencoded
Accept: */*

"grant_type": "client_credentials",
"scope": "",
"client_id": “xxxxxxx”,
"client_secret": "xxxxxxxx"

A resposta dessa requisição deve seguir o seguinte padrão:

{
    "access_token": "ff16597f-6ff5-4fbe-9ad2-e819955e990a",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "xxxxxxxx"
}