Saltar para o conteúdo
AurionAI

API para Programadores: utilização e webhooks

4 min de leituraPor Emmanuel Yazbeck

As páginas da API de programador mostram como os programas utilizam a API do AurionAI e permitem enviar eventos do AurionAI para os seus próprios sistemas através de webhooks.

Disponibilidade: todos os perfis. Apenas administradores.

Pré-requisitos

  • Tem a função Proprietário ou Administrador. Outras funções não podem abrir estas páginas.
  • Para webhooks: um endereço HTTPS do seu lado que aceite pedidos POST com um corpo JSON.

Abrir as páginas da API de programador

  1. Na barra superior, selecione o seu nome ou fotografia para abrir o menu de utilizador.
  2. Selecione Definições do Inquilino.
  3. Aceda ao cartão API de Programador.
  4. Selecione Painel de utilização da API ou Gestão de webhooks.

O cartão API de Programador na página de Definições do Tenant.

Rever a utilização da API

A página "API Usage Dashboard" mostra o tráfego da API do AurionAI para a sua organização.

  1. Em "Window", escolha "Last 1 day", "Last 7 days" ou "Last 30 days". O valor predefinido é sete dias.
  2. Leia os quatro totais: "Total Requests", "Error Rate", "Rate-Limit Hits" e "Webhook Success".
  3. Leia "Top API Paths" para ver quais os endereços mais chamados, com os respetivos erros.
  4. Leia "Daily Trend" para ver o tráfego por dia.
  5. Selecione "Refresh" para carregar os números mais recentes.

Registar um webhook

  1. Na página "Webhook Management", aceda a "Create Subscription".
  2. Em "Target URL", escreva o endereço HTTPS do seu recetor.
  3. Em "Events", selecione os eventos que pretende receber. Os eventos estão agrupados: conversas, mensagens, contactos, tickets, chamadas, base de conhecimento e sistema.
  4. Selecione "Create webhook".
  5. Uma caixa de diálogo mostra o segredo de assinatura. Selecione "Copy secret" e guarde o segredo num local seguro. O AurionAI mostra-o apenas uma vez.
  6. Selecione "I have saved my secret".

O novo webhook aparece em "Subscriptions" com o estado "Active".

Verificar uma assinatura de webhook

Cada entrega é um pedido POST com um corpo JSON e os seguintes cabeçalhos:

  • X-Webhook-Event: o nome do evento, por exemplo ticket.created.
  • X-Webhook-Timestamp: a hora da entrega.
  • X-Webhook-Signature: a assinatura da entrega.

Para verificar que uma entrega provém do AurionAI:

  1. Tome o valor de X-Webhook-Timestamp, um ponto e o corpo bruto do pedido, por esta ordem.
  2. Calcule um HMAC-SHA256 deste texto com o seu segredo de assinatura.
  3. Escreva o resultado em hexadecimal e compare-o com X-Webhook-Signature. Aceite a entrega apenas quando forem iguais.

Testar, pausar ou eliminar um webhook

  • Selecione "Send test" para enviar uma entrega de teste. Um webhook pausado não pode receber um teste.
  • Selecione "Pause" para interromper as entregas durante algum tempo e "Resume" para as retomar.
  • Selecione "Delete" e confirme para remover o webhook.
  • A página lista as entregas mais recentes, com o respetivo estado, o número de tentativas e o estado HTTP do seu recetor.

Resultado

O AurionAI envia cada evento selecionado para o seu endereço. Uma entrega é considerada bem-sucedida quando o seu recetor responde com um estado 2xx. Caso contrário, o AurionAI tenta novamente mais tarde, até um total de cinco tentativas.

Se algo correr mal

  • "Webhook URL is required." Escreva o endereço do seu recetor.
  • "Select at least one event to subscribe to." Selecione pelo menos um evento.
  • Uma mensagem indica que o URL do webhook deve começar com https. O AurionAI envia webhooks apenas para endereços HTTPS.
  • Uma mensagem indica que o endereço está bloqueado ou não pode ser resolvido. O AurionAI recusa endereços privados, locais e desconhecidos. Utilize um endereço público que seja resolvido no DNS.
  • A assinatura não corresponde. Utilize o corpo bruto tal como foi recebido, antes de qualquer análise. Utilize o segredo deste webhook. Se perdeu o segredo, elimine o webhook e crie-o novamente.
  • As entregas falham. Verifique o estado HTTP na lista de entregas. O seu recetor deve responder com um estado 2xx.
  • "No webhooks configured" em "Webhook Success". A sua organização ainda não tem nenhum webhook de programador.

Artigos relacionados

Ainda precisa de ajuda? Envie um pedido ou .