Skip to main content
Acessar Studio

Webhook

O webhook permite disparar um robô por meio de uma chamada de API — integrando o Roberty com outros sistemas, plataformas ou scripts. É a forma mais comum de conectar o Roberty a sistemas externos, como ERPs, CRMs, formulários web ou qualquer aplicação que consiga fazer uma requisição HTTP.

Como funciona​

Cada robô pode ter um token de webhook único e secreto. Quando outro sistema envia uma requisição para a API do Roberty com esse token, o robô é disparado imediatamente. É possível passar dados para o robô na requisição e, opcionalmente, receber uma resposta personalizada de volta.

Gerando o token do webhook​

  1. Abra o Designer do robô desejado.
  2. Clique no ícone de engrenagem (⚙️) para abrir as configurações.
  3. Localize a seção Token para Webhook.
  4. Clique no ícone de geração de token.
  5. Confirme a criação quando solicitado.
  6. Copie o token gerado.
Mantenha o token em segredo

O token de webhook concede acesso para disparar o robô remotamente. Não compartilhe o token com pessoas que não sejam responsáveis pelo desenvolvimento do robô. Caso o token seja comprometido, gere um novo para invalidar o anterior.

Disparando o robô via POST​

Envie uma requisição POST para o endpoint abaixo, passando o token no cabeçalho e os argumentos no corpo da requisição.

Endpoint:

POST https://api.roberty.app/main/public/webhook/request

Cabeçalho obrigatório:

x-roberty-token: <seu-token-aqui>

Corpo da requisição (JSON):

{
  "nome": "Roberty",
  "documento": "123.456.789-00"
}

Os valores enviados no corpo ficam disponíveis no robô como argumentos, acessíveis via campos de expressão ou código personalizado.

Disparando o robô via GET​

Também é possível disparar o robô por meio de uma requisição GET, passando os argumentos diretamente na URL.

Exemplo:

GET https://api.roberty.app/main/public/webhook/request?nome=Roberty&documento=123.456.789-00

O cabeçalho x-roberty-token continua sendo obrigatório mesmo em requisições GET.

Acompanhando a execução​

A resposta da requisição de disparo inclui um identificador chamado webhookCallId. Use-o para consultar o status e o resultado da execução:

Endpoint de consulta:

GET https://api.roberty.app/prod/1/customer/robot/webhookResponse/{webhookCallId}

Possíveis status de retorno:

StatusSignificado
WAITINGO robô está em execução e ainda não retornou uma resposta.
DONEA execução foi concluída com uma resposta personalizada.

Retornando uma resposta personalizada​

Para que o robô envie dados de volta ao sistema que o disparou, adicione a ação Responder Webhook ao fluxo. Esta ação permite retornar um objeto com os dados desejados.

Exemplo de retorno:

{
  "response": { "status": "processado", "codigo": "NF-00123" },
  "status": "DONE"
}

Sem essa ação, a consulta ao webhookCallId retornará WAITING enquanto o robô executar.

Próximos passos​