O que são webhooks e como enviá-los ao seu data warehouse

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.

Criando webhooks na plataforma da Kondado

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

Códigos de resposta do webhook

A resposta da URL sempre retornará o código 200 com 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.

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)
• NO_PARAMETERS_PROVIDED. Indica que a URL está mal formatada e nenhum parâmetro foi fornecido
• PIPELINE_NOT_FOUND. Indica que o pipeline_id fornecido não foi encontrado ou token e key fornecidos não tem autorização para acessá-los
• NOT_AUTHORIZED. Indica que token e key fornecidos não são válidos ou estão inativos
• PIPELINE_NOT_ACTIVE. Indica que a integração indicada por pipeline_id está desativada
• NO_BODY_PROVIDED. Indica que nenhum body foi fornecido durante o POST
• WRONG_PIPELINE_TYPE. Indica que a integração indicada por pipeline_id não é do tipo webhook
• UKNOWN_ERROR. Erro genérico que aponta algum problema não mapeado. Caso encontre esse erro, entre em contato conosco indicando a URL que usou para a chamada