Webhooks de entrada

Webhooks desta página são de entrada: um sistema externo envia um payload para a Colmeia, que o processa conforme o mapeamento e a ação configurados no endpoint. Esta API não promete notificações de eventos de saída.

Os endpoints de administração usam a base URL https://app.usecolmeia.com/api/v1 e autenticação Bearer.

Administrar endpoints existentes

GET /webhooks

Lista os endpoints do time. Use page e limit para paginação (1 e 20 por padrão; máximo 100) e active=true ou active=false para filtrar pelo estado.

curl "https://app.usecolmeia.com/api/v1/webhooks?active=true" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

GET /webhooks/:id

Obtém um endpoint existente pelo UUID.

PUT /webhooks/:id

Use este endpoint apenas para administrar name e is_active de um endpoint existente. is_active controla se o receiver aceita o endpoint; name é administrativo. A configuração que o receiver efetivamente consome — ação e mapeamento — deve ser feita pelo painel. Embora o handler v1 ainda aceite campos legados, o receiver usa action_type e action_config, e o backfill desses campos foi único.

DELETE /webhooks/:id

Exclui permanentemente um endpoint existente.

Criação temporariamente indisponível na API v1

POST /webhooks não está disponível para uso até uma correção separada da API. O handler ainda grava secret_token_hash (o schema atual usa signing_secret_hash) e não preenche endpoint_id, que é obrigatório para o receiver. Crie novos endpoints pelo painel de Webhooks, que usa o fluxo compatível com o schema.

Ao criar um endpoint pelo painel, copie o segredo exibido naquele momento. Ele é mostrado uma única vez e a API v1 não permite recuperá-lo posteriormente.

Enviar um webhook para a Colmeia

POST /webhooks/inbound/:endpointId

Esta é a URL que o sistema externo deve consumir. O endpointId é o identificador público retornado na criação pelo painel, distinto do UUID usado nos endpoints administrativos.

Envie JSON e o segredo compartilhado no header X-Webhook-Secret. Quando o request traz Content-Length e ele é maior que 1 MB, o receiver responde 413. Sem esse header, o handler atual chama request.json() sem um limite efetivo observado; portanto, 1 MB não é um limite rígido universal. Use payloads de até 1 MB por compatibilidade.

curl -X POST "https://app.usecolmeia.com/api/v1/webhooks/inbound/endpoint_publico_de_exemplo" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: whsec_segredo_de_exemplo" \
  -d '{
    "name": "Contato de exemplo",
    "email": "contato@empresa-exemplo.test"
  }'

O header X-Sonar-Webhook-Secret é aceito somente como alias legado. Use X-Webhook-Secret em novas integrações.

Como a validação funciona

A Colmeia compara o segredo compartilhado recebido com o hash armazenado para o endpoint. Este fluxo de entrada não exige um esquema adicional de assinatura.

Depois da autenticação, a Colmeia processa o payload conforme o mapeamento de campos e a ação configurada no endpoint. No fluxo processado, a resposta tem o formato próprio { received, success, action, entity_id, entity_type, error? }; error é opcional. Adapte o payload à configuração criada no painel.

{
  "received": true,
  "success": true,
  "action": "create_deal",
  "entity_id": "33333333-3333-4333-8333-333333333333",
  "entity_type": "deal"
}

O status HTTP 200 confirma apenas que o receiver respondeu. Uma ação pode retornar success: false e error com 200; uma exceção inesperada retorna 200 somente com { "received": true, "error": "Processing error" }, sem success, action ou entidades. A integração deve considerar o processamento concluído apenas quando success === true.

GET /webhooks/inbound/:endpointId

Alguns provedores verificam a URL com GET. Para um endpoint ativo, a rota responde { "status": "active" } sem processar payload; para um endpoint ausente ou inativo, retorna 404.

Respostas e erros

Status	Situação
`200`	Receiver respondeu. Aceite o processamento somente quando `success === true`; a resposta de exceção pode trazer apenas `received` e `error`.
`400`	Corpo JSON inválido.
`401`	`X-Webhook-Secret` ausente ou inválido para um endpoint protegido.
`404`	Endpoint inexistente ou inativo.
`413`	`Content-Length` presente e maior que 1 MB.

Webhooks

On this page