API de Webhooks de Entrada

Visao Geral

Webhooks de entrada permitem que plataformas externas (ex.: gateways de pagamento, CRMs, ferramentas de marketing) enviem dados para a Paralela por meio de URLs unicas. Quando uma requisicao e recebida, ela pode acionar automacoes do flow builder ou outras integracoes.

Endpoint Publico

Receber Webhook

POST|GET|PUT|DELETE /webhook/incoming/:token

Autenticacao: Baseada em token (o token faz parte da URL)

Limite de requisicoes: 100 requisicoes por minuto por IP

Headers (opcional):

• X-Webhook-Signature: Assinatura HMAC-SHA256 (obrigatorio se um segredo estiver configurado para a integracao)

Corpo da requisicao: Qualquer payload JSON

Resposta:

{
  "success": true,
  "message": "Webhook processed successfully",
  "webhookIntegrationId": 123
}

Respostas de Erro

Codigo	Descricao
400	Requisicao invalida (ex.: token malformado)
401	Assinatura invalida ou ausente (quando HMAC esta configurado)
403	Webhook esta desabilitado
404	Token invalido
405	Metodo HTTP nao permitido
429	Limite de requisicoes excedido
500	Erro interno do servidor

Formato da resposta de erro:

{
  "error": "Invalid webhook signature"
}

Validacao de Assinatura HMAC

Se um segredo estiver configurado para a integracao de webhook, as requisicoes devem incluir o header X-Webhook-Signature contendo uma assinatura HMAC-SHA256 do corpo da requisicao.

Geracao da Assinatura

A assinatura e calculada como:

signature = HMAC-SHA256(request_body, secret).hexdigest()

Exemplos

Python:

import hmac
import hashlib
import json
import requests

secret = "your-webhook-secret"
payload = {"event": "order.created", "data": {"id": 123}}
body = json.dumps(payload)

signature = hmac.new(
    secret.encode(),
    body.encode(),
    hashlib.sha256
).hexdigest()

response = requests.post(
    "https://api.example.com/webhook/incoming/your-token-here",
    json=payload,
    headers={
        "Content-Type": "application/json",
        "X-Webhook-Signature": signature
    }
)

Node.js:

const crypto = require('crypto');
const axios = require('axios');

const secret = 'your-webhook-secret';
const payload = { event: 'order.created', data: { id: 123 } };
const body = JSON.stringify(payload);

const signature = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

await axios.post(
  'https://api.example.com/webhook/incoming/your-token-here',
  payload,
  {
    headers: {
      'Content-Type': 'application/json',
      'X-Webhook-Signature': signature
    }
  }
);

cURL:

SECRET="your-webhook-secret"
PAYLOAD='{"event":"order.created","data":{"id":123}}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST "https://api.example.com/webhook/incoming/your-token-here" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

API de Gerenciamento

Esses endpoints requerem autenticacao e sao usados para gerenciar as configuracoes de webhooks de entrada.

Gerar Token de Webhook

Gera um novo token de webhook de entrada para uma integracao existente.

POST /api/webhook-integrations/:id/incoming-token

Autenticacao: Obrigatoria (JWT)

Permissoes: webhooks:update

Resposta:

{
  "token": "a1b2c3d4e5f6...",
  "url": "https://api.example.com/webhook/incoming/a1b2c3d4e5f6..."
}

Atualizar Configuracoes do Webhook de Entrada

Atualiza as configuracoes de um webhook de entrada.

PUT /api/webhook-integrations/:id

Autenticacao: Obrigatoria (JWT)

Permissoes: webhooks:update

Corpo da requisicao:

{
  "incomingWebhookEnabled": true,
  "incomingWebhookMethods": ["POST", "PUT"],
  "incomingWebhookSecret": "optional-secret-for-hmac"
}

Visualizar Ultima Requisicao

Obtem detalhes sobre a ultima requisicao recebida pelo webhook.

GET /api/webhook-integrations/:id

Autenticacao: Obrigatoria (JWT)

Permissoes: webhooks:view

Resposta (inclui incomingWebhookLastRequest):

{
  "id": 1,
  "name": "Payment Gateway Webhook",
  "incomingWebhookEnabled": true,
  "incomingWebhookMethods": ["POST"],
  "incomingWebhookLastRequest": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "method": "POST",
    "headers": {
      "content-type": "application/json",
      "authorization": "[REDACTED]"
    },
    "body": {
      "event": "payment.completed",
      "data": {}
    },
    "ip": "203.0.113.50",
    "statusCode": 200
  }
}

Consideracoes de Seguranca

Seguranca do Token

• Os tokens possuem 48 caracteres e sao gerados de forma criptograficamente aleatoria
• Os tokens devem ser tratados como segredos e nao compartilhados publicamente
• Regenere os tokens caso sejam comprometidos

Validacao HMAC

• Habilite a validacao HMAC para webhooks em producao
• Use segredos fortes, gerados aleatoriamente (no minimo 32 caracteres)
• Armazene os segredos de forma segura; eles nao podem ser recuperados apos a criacao

Sanitizacao de Headers

Os seguintes headers sao automaticamente ocultados quando armazenados no log da ultima requisicao:

• authorization
• x-api-key
• x-auth-token
• x-webhook-signature
• cookie
• set-cookie
• x-access-token
• x-secret-key
• api-key
• apikey

Limitacao de Taxa

• Limite padrao: 100 requisicoes por minuto por endereco IP
• Retorna 429 Too Many Requests quando excedido
• Tente novamente apos a janela de limite ser reiniciada

Integracao com o Flow Builder

Quando um webhook de entrada e recebido:

1. O token e validado
2. A assinatura HMAC e verificada (se configurada)
3. O fluxo associado e acionado com os dados do webhook
4. Os metadados da requisicao sao armazenados para depuracao

Variaveis Disponiveis no Fluxo

Quando um fluxo e acionado por um webhook de entrada, as seguintes variaveis estao disponiveis:

Variavel	Descricao
source	Sempre "incoming_webhook"
method	Metodo HTTP (GET, POST, PUT, DELETE)
headers	Objeto com os headers da requisicao
body	Corpo da requisicao (JSON parseado)
query	Parametros da query string
ip	Endereco IP do cliente
timestamp	Timestamp da requisicao em formato ISO 8601

Solucao de Problemas

Problemas Comuns

404 - Token de webhook invalido

• Verifique se o token esta correto e completo
• Confirme que a integracao existe e possui um token configurado

403 - Webhook esta desabilitado

• Habilite o webhook de entrada nas configuracoes da integracao

405 - Metodo nao permitido

• Verifique os metodos permitidos nas configuracoes da integracao
• Certifique-se de que sua requisicao usa um metodo HTTP permitido

401 - Assinatura ausente ou invalida

• Certifique-se de que o header X-Webhook-Signature esta presente
• Verifique se a assinatura foi calculada corretamente
• Confirme que voce esta usando o segredo correto
• Certifique-se de que o corpo da requisicao nao foi modificado

429 - Limite de requisicoes excedido

• Reduza a frequencia de requisicoes
• Implemente backoff exponencial
• Entre em contato com o suporte para limites maiores, se necessario