Webhook

Quando você faz uma integração usando os mais de 50 conectores que temos na plataforma da Kondado, a nossa plataforma se encarrega de “ler” os dados dessas origens e inserir no seu Data Warehouse ou Data Lake.

Quando esse conector é uma ferramenta (por exemplo Google Ads, Facebook ou Pipedrive), nós fazemos essa leitura via API para obter as informações que você deseja.

Webhooks podem ser considerados como “APIs reversas”: ao invés de a nossa plataforma ler de forma pró-ativa as informações, é o conector que envia os dados para a nossa plataforma e nós inserimos do webhook para o Data Warehouse.

Adicionando o conector

1) Antes de adicionar um webhook, é importante que você leia esse post sobre como gerenciar os seus tokens de acesso e crie um token que será responsável por autenticar o seu webhook.

2) Uma vez na nossa plataforma, vá para a seção de adicionar conectores, selecione o conector de webhook e adicione-o. Não é necessário fornecer informações de acesso nesse momento, basta dar um nome para o seu novo conector e salvá-lo.

3) Com o conector adicionado, vá para a seção de integrações e clique em “Nova integração”

4) Siga o fluxo normal de criação de integrações, selecionando o novo conector de webhooks como origem

5) Uma vez criada a integração, acesse-a e, na barra de endereço do seu navegador, copie o id da integração, que é o código numérico ao final de “app.kondado.com.br/pipelines/XXXX“

Enviando informações para o seu webhook

O seu novo webhook aceita requisições do tipo POST e irá enviar para o seu destino o body da chamada, que deve ser do tipo JSON.

O endereço do seu webhook é composto da seguinte forma:

URL Base

https://k1.kondado.com.br

Parâmetros obrigatórios

• pipeline_id: código da sua integração, obtido no passo (5)
• key: chave do seu token, obtido no passo (1)
• token: o seu token, obtido no passo (2)

Exemplo de URL

Combinando a URL base e os parâmetros, a sua chamada irá se parecer com a seguinte:

https://k1.kondado.com.br?pipeline_id=835212&token=oseutokenaqui&key=achavedoseutokenaqui

Com a sua URL criada, basta adicioná-la na sua ferramenta ou aplicação e fazer posts nela com o body que deseja enviar ao seu datawarehouse.

ATENÇÃO: Cuidado para não confundir token e key ao adicioná-los na URL. Para diferenciá-los com maior facilidade, lembre-se que a key terá um formato com hífens, como por exemplo “d538b946-9d55-405a-9bd2-72d74b1cb8f5” e o token será uma longa sequencia de números e letras, mas sem hífens

Veja um exemplo de utilização de webhooks

https://kondado.com.br/blog/integrando-conversoes-do-rdstation-ao-seu-data-warehouse-via-webhook/

Códigos de resposta do webhook

A resposta da URL retornará o código 200 em caso de sucesso e 400 em caso de falha. Na resposta, haverá um JSON, cujo formato pode ser:

Inserção bem-sucedida

A inserção bem-sucedida retornará um JSON no formato abaixo, onde a variável “success” virá como true e haverá uma outra variável “data”, que contém informações sobre o request.

{
    "success": true,
    "data": {
        "__kdd_request_id": "rydjemeilmsqkqvjtfkc",
        "__kdd_request_unix_timestamp": 1577015690.3118637
    }
}

• __kdd_request_id: id da execução do webhook, que será inserido no seu data warehouse
• __kdd_request_unix_timestamp: UNIX timestamp (em UTC) que indica quando o request aconteceu. Também será inserido no seu data warehouse

Você pode usar as variáveis enviadas em “data” para manter algum tipo de log na sua aplicação.

A inserção bem sucedida não significa que o seus dados serão processados. Após receber uma resposta de sucesso, os dados ainda passarão por uma validação de autenticação em um segundo momento e a resposta negativa de autenticação não será retornada – os dados apenas serão descartados. A resposta positiva você poderá conferir uma vez que os dados sejam inseridos no seu destino

Inserção mal-sucedida

A inserção mal-sucedida retorna um JSON como o abaixo, onde “success” será false e a variável “error” trará o código de erro encontrado.

{
    "success": false,
    "error": "ERROR_CODE"
}

Códigos de erro e os seus significados:

• MISSING_PARAMETER: parameter_key. Indica que a URL está mal-formatada e o parâmetro indicado por parameter_key não foi fornecido (lembrando que são obrigatórios os parâmetros pipeline_id, key e token)
• INVALID_PARAMETER: parameter_key: o valor do parâmetro informado é inválido
• NO_PARAMETERS_PROVIDED. Indica que a URL está mal formatada e nenhum parâmetro foi fornecido
• NO_BODY_PROVIDED. Indica que nenhum body foi fornecido durante o POST

Integrações

Gráfico de relacionamento entre tabelas

Post raw JSON

• __kdd_request_body irá receber o JSON do post