Os Webhooks permitem integrar sistemas ao Produttivo por meio do envio automático de notificações sempre que determinados eventos acontecem.

Essa funcionalidade está disponível em fase beta e precisa ser habilitada mediante solicitação. Durante esse período, ajustes e melhorias poderão ser realizados, sendo todas as alterações comunicadas previamente.

O que são Webhooks no Produttivo

Webhooks são notificações enviadas automaticamente pelo Produttivo para uma URL configurada por sua equipe.

Com eles, é possível receber informações em tempo real quando eventos específicos ocorrerem no sistema, como:

Finalização de atividades;
Revisão de atividades;
Conclusão de exportações de relatórios.

Como configurar um Webhook

Para configurar um Webhook, envie as informações abaixo para o responsável pelo seu projeto no Produttivo.

Em versões futuras, essa configuração poderá ser realizada diretamente pela tela de integrações do sistema.

Subscription URL

URL que receberá as notificações enviadas pelo Produttivo.

Topic

Define quais eventos serão monitorados.

Atualmente, estão disponíveis os seguintes tópicos:

Topic	Descrição
`work.finished`	Notifica quando uma atividade é finalizada
`work.reviewed`	Notifica quando uma atividade é revisada
`export_request.available`	Notifica quando uma exportação de PDF é concluída

HTTP Auth Username (opcional)

Usuário utilizado para autenticação HTTP padrão.

HTTP Auth Password (opcional)

Senha utilizada para autenticação HTTP padrão.

Secret Key (opcional)

Chave utilizada para assinatura das notificações enviadas pelo Produttivo.

Estrutura da notificação enviada pelo Webhook

Todas as notificações seguem uma estrutura padrão.

Campos da notificação

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}).

Exemplo de notificação de atividade 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
  }
}

Exemplo de notificação de 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.

Tempo limite da resposta

A URL configurada deve responder em até 10 segundos.

Caso esse prazo seja excedido, o Produttivo realizará apenas mais uma tentativa de envio 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"
}

Precisa de ajuda?

Se precisar de suporte durante a configuração dos Webhooks, entre em contato com nosso time de Atendimento pelo chat. Teremos prazer em ajudar 💚

Como utilizar Webhooks para integração com o Produttivo