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
Publicado em 2019-12-22