API de Webhooks de Entrada

Visão Geral

Os webhooks de entrada da Paralela permitem que plataformas externas (ex.: gateways de pagamento, CRMs, ferramentas de marketing) enviem dados para a Paralela por meio de URLs únicas. Quando uma requisição é recebida, ela pode acionar automações do flow builder ou outras integrações.

Endpoint Público

Receber Webhook

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

Autenticação: Baseada em token (o token faz parte da URL)

Limite de requisições: 100 requisições por minuto por IP

Headers (opcional):

• X-Webhook-Signature: Assinatura HMAC-SHA256 (obrigatório se um segredo estiver configurado para a integração)

Corpo da requisição: Qualquer payload JSON

Resposta:

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

Respostas de Erro

Código	Descrição
400	Requisição inválida (ex.: token malformado)
401	Assinatura inválida ou ausente (quando HMAC está configurado)
403	Webhook está desabilitado
404	Token inválido
405	Método HTTP não permitido
429	Limite de requisições excedido
500	Erro interno do servidor

Formato da resposta de erro:

{
  "error": "Invalid webhook signature"
}

Validação de Assinatura HMAC

Se um segredo estiver configurado para a integração de webhook, as requisições devem incluir o header X-Webhook-Signature contendo uma assinatura HMAC-SHA256 do corpo da requisição.

Geração da Assinatura

A assinatura é 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.suaempresa.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.suaempresa.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.suaempresa.com/webhook/incoming/your-token-here" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

API de Gerenciamento

Esses endpoints requerem autenticação e são usados para gerenciar as configurações de webhooks de entrada.

Gerar Token de Webhook

Gera um novo token de webhook de entrada para uma integração existente.

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

Autenticação: Obrigatória (JWT)

Permissões: webhooks:update

Resposta:

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

Atualizar Configurações do Webhook de Entrada

Atualiza as configurações de um webhook de entrada.

PUT /api/webhook-integrations/:id

Autenticação: Obrigatória (JWT)

Permissões: webhooks:update

Corpo da requisição:

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

Visualizar Última Requisição

Obtém detalhes sobre a última requisição recebida pelo webhook.

GET /api/webhook-integrations/:id

Autenticação: Obrigatória (JWT)

Permissões: 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
  }
}

Considerações de Segurança

Segurança do Token

• Os tokens possuem 48 caracteres e são gerados de forma criptograficamente aleatória
• Os tokens devem ser tratados como segredos e não compartilhados publicamente
• Regenere os tokens caso sejam comprometidos

Validação HMAC

• Habilite a validação HMAC para webhooks em produção
• Use segredos fortes, gerados aleatoriamente (no mínimo 32 caracteres)
• Armazene os segredos de forma segura; eles não podem ser recuperados após a criação

Sanitização de Headers

Os seguintes headers são automaticamente ocultados quando armazenados no log da última requisição:

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

Limitação de Taxa

• Limite padrão: 100 requisições por minuto por endereço IP
• Retorna 429 Too Many Requests quando excedido
• Tente novamente após a janela de limite ser reiniciada

Integração com o Flow Builder

Quando um webhook de entrada é recebido:

1. O token é validado
2. A assinatura HMAC é verificada (se configurada)
3. O fluxo associado é acionado com os dados do webhook
4. Os metadados da requisição são armazenados para depuração

Variáveis Disponíveis no Fluxo

Quando um fluxo é acionado por um webhook de entrada, as seguintes variáveis estão disponíveis:

Variável	Descrição
source	Sempre "incoming_webhook"
method	Método HTTP (GET, POST, PUT, DELETE)
headers	Objeto com os headers da requisição
body	Corpo da requisição (JSON parseado)
query	Parâmetros da query string
ip	Endereço IP do cliente
timestamp	Timestamp da requisição em formato ISO 8601

Solução de Problemas

Problemas Comuns

404 - Token de webhook inválido

• Verifique se o token está correto e completo
• Confirme que a integração existe e possui um token configurado

403 - Webhook está desabilitado

• Habilite o webhook de entrada nas configurações da integração

405 - Método não permitido

• Verifique os métodos permitidos nas configurações da integração
• Certifique-se de que sua requisição usa um método HTTP permitido

401 - Assinatura ausente ou inválida

• Certifique-se de que o header X-Webhook-Signature está presente
• Verifique se a assinatura foi calculada corretamente
• Confirme que você está usando o segredo correto
• Certifique-se de que o corpo da requisição não foi modificado

429 - Limite de requisições excedido

• Reduza a frequência de requisições
• Implemente backoff exponencial
• Entre em contato com o suporte para limites maiores, se necessário