Webhooks
Um webhook é um endereço HTTPS do seu sistema que o NearOne Trust chama sozinho quando algo acontece: um relato chegou, um caso mudou de etapa, o prazo de um caso está perto do fim, um membro foi convidado. Em vez de o seu sistema perguntar à API de tempos em tempos ("chegou alguma coisa?"), o NearOne Trust avisa no momento em que o fato acontece.
Com webhooks você consegue, por exemplo:
- abrir um chamado no seu ITSM ou um card no seu quadro quando um relato é registrado;
- alimentar um painel de compliance com as mudanças de etapa e os encerramentos;
- acionar o plantão quando o prazo de um caso vence;
- manter um cadastro espelho de empresas, membros ou papéis.
Os eventos do canal de denúncias trazem apenas referências e classificações do caso (código, canal, empresa, tipo, fase, etapa, prioridade e situação do prazo). Nunca trazem o texto do relato, mensagens, anexos, nome ou identidade de quem relatou, modo de identificação ou responsável. Para ler um caso, o seu sistema chama a API com uma chave autorizada. Assim, mesmo que o endpoint receptor seja comprometido ou mal configurado, nenhum relato vaza por ele.
Como funciona, de ponta a ponta
- Algo acontece na organização e o evento entra numa fila de entregas, uma entrega por endpoint inscrito naquele tipo de evento.
- Um processo em segundo plano faz um
POSTcom o corpo JSON assinado para a URL do endpoint. - O seu sistema confere a assinatura, responde rapidamente com um código
2xxe processa o evento depois. - Se precisar de detalhes, o seu sistema consulta a API usando o código do caso que veio no evento.
Os eventos reporting.case.* são publicados a partir da linha do tempo do caso, depois que o fato foi gravado. Na prática chegam em segundos, mas não no mesmo instante da ação na tela. Não conte com ordem garantida entre eventos diferentes: use o campo created_at e consulte o estado atual do caso na API quando a ordem importar.
Criar um webhook no painel
Webhooks ficam em Integração › Webhooks. Para ver a lista é preciso a permissão Ver webhooks; para criar, alterar, pausar, testar, reenviar, trocar o segredo ou revogar, a permissão Gerir webhooks.

- Clique em Novo webhook.
- Preencha Nome: identifique o sistema que vai receber os eventos (por exemplo, "ERP de produção"). Até 120 caracteres.
- Preencha URL: o endereço do seu endpoint. Precisa ser
https://, ter até 2048 caracteres e apontar para um endereço público na internet. - Em Eventos, marque os tipos que este endpoint deve receber. Marque pelo menos 1 e no máximo 20: sem nenhum evento marcado, o cadastro é recusado (erro
webhook_kinds_invalid). O botão Eventos e exemplos abre o catálogo com a descrição de cada evento, um exemplo de corpo e o passo a passo de validação da assinatura. - Clique em Criar webhook.
- A janela Segredo do webhook mostra o segredo, que começa com
whsec_. Copie e guarde agora: ele não aparece de novo. Depois disso, a tela mostra apenas o Prefixo (os primeiros caracteres), para você conferir qual segredo está em uso.
Cada organização pode ter até 25 webhooks ativos ao mesmo tempo (revogados não contam). Acima disso o cadastro é recusado com o erro webhook_limit_exceeded.
Cada evento marcado gera uma entrega por ocorrência. Um endpoint inscrito só em reporting.case.received e reporting.case.closed recebe muito menos tráfego (e tem menos a validar) do que um inscrito em tudo.
- Só
https. Endereçoshttp,localhost, domínios.locale IPs privados, de loopback ou reservados são recusados (errowebhook_url_invalidouwebhook_url_insecure). - A URL não pode conter usuário e senha (
https://user:pass@...) nem fragmento (#...). - O nome do host é resolvido a cada entrega e o endereço resolvido é conferido de novo. Se o DNS passar a apontar para um IP privado, a entrega é recusada sem fazer a chamada.
- Redirecionamentos não são seguidos. Uma resposta
301/302conta como falha. Cadastre a URL final.
Pela API
O mesmo cadastro pode ser feito com uma chave de API que tenha a permissão de gerir webhooks:
curl -X POST https://api.trust.nearone.com.br/api/v1/webhooks \
-H "Authorization: Bearer $NEARONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "ERP de produção",
"url": "https://erp.suaempresa.com.br/hooks/nearone",
"event_kinds": ["reporting.case.received", "reporting.case.closed"]
}'
A resposta 201 traz o webhook com o campo secret (mostrado só nesta resposta) e o code, um código de 4 caracteres que identifica o webhook nas demais rotas (/api/v1/webhooks/{code}). Veja Create Webhook e a lista oficial de eventos em List Event Kinds.
O que chega no seu endpoint
Requisição
Cada entrega é um POST com corpo JSON (UTF-8) e estes cabeçalhos:
| Cabeçalho | Exemplo | Para que serve |
|---|---|---|
Content-Type | application/json | O corpo é JSON. |
User-Agent | NearOneTrust-Webhooks/1.0 | Identifica a origem da chamada. |
X-Sg-Event | reporting.case.received | O tipo do evento. Útil para rotear sem abrir o corpo. |
X-Sg-Delivery | 5f0c… (UUID) | O identificador desta entrega. É o mesmo em todas as tentativas e no reenvio manual. |
X-Sg-Signature | t=1763320330,v1=9a4f… | Assinatura HMAC-SHA256 do corpo. Veja Validar a assinatura. |
Envelope do evento
Todos os eventos compartilham o mesmo envelope. O que muda de um tipo para outro é o objeto data.
{
"id": "0b6f3c1e-5d7a-4e0b-9a52-6f1f3f6f2a10",
"kind": "reporting.case.stage_changed",
"created_at": "2026-11-09T14:32:10.512Z",
"organization_id": "6c0c9a52-1f4e-4d3b-8a77-2b9d5e1c4f30",
"resource_type": "reporting_case",
"resource_id": "c1a7e0d4-8b35-4f6a-9d12-7e3b5a9c0f48",
"actor_type": "system",
"request_id": "b2d4e6f8a0c24e6f8a0c2e4f6a8b0c2d",
"data": {
"case_code": "8WG8",
"channel": "denuncias",
"company_code": "PE57",
"type": "fraude_corrupcao",
"phase": "in_progress",
"stage_key": "analysis",
"priority": "high",
"sla_state": "on_track"
}
}
| Campo | Descrição |
|---|---|
id | Identificador do evento. Se o mesmo evento for entregue a dois endpoints seus, os dois recebem o mesmo id. |
kind | Tipo do evento (igual ao cabeçalho X-Sg-Event). |
created_at | Quando o evento foi registrado (ISO 8601, UTC). |
organization_id | A organização em que o evento aconteceu. |
resource_type | Tipo do recurso: reporting_case para casos, company, org_membership, role etc. para os demais. |
resource_id | UUID do recurso. É null para eventos de caso protegido. |
actor_type | Quem originou: system nos eventos de caso; identity (pessoa) ou api_key nos eventos de cadastro. |
request_id | Identificador da requisição que originou o evento, quando houver. Útil para cruzar com a auditoria e com o suporte. |
data | Dados do evento. Nos eventos de caso, as referências abaixo. Nos demais, poucos dados da mudança (pode ser {}). |
data nos eventos de caso (reporting.case.*)
| Campo | Exemplo | Significado |
|---|---|---|
case_code | 8WG8 | Código de 4 caracteres do caso. É o mesmo que a equipe vê no painel e é o que você usa na API (/api/v1/requests/demands/{case_code}). Não é o protocolo de quem relatou. |
channel | denuncias | Identificador (slug) do canal pelo qual o relato chegou. |
company_code | PE57 | Código da empresa do caso. |
type | assedio_moral | Chave da categoria do relato. |
phase | in_progress | Fase do caso: pending, in_progress, waiting, scheduled ou closed. |
stage_key | received | Chave da etapa atual no fluxo de tratamento. |
priority | normal | Prioridade: normal, high ou urgent. |
sla_state | at_risk | Situação do prazo: on_track, at_risk, overdue, paused, met, missed ou none (sem prazo). |
Casos protegidos são sensíveis até na existência. Por padrão, nenhum evento de caso protegido é enviado. Se o seu endpoint precisa saber que "algo aconteceu" (por exemplo, para contar volume), ative Receber aviso de casos protegidos na página do webhook. A partir daí ele recebe os eventos desses casos apenas com a marca:
{ "resource_type": "reporting_case", "resource_id": null, "data": { "protected": true } }
Sem código, canal, empresa ou tipo. A ativação pede confirmação e fica registrada na auditoria.
Exemplo de corpo enviado de verdade
Na página de um webhook, a seção Entregas lista as entregas (colunas Evento, Estado, Tentativas, HTTP, Duração e Quando). Abra uma entrega para ver o Corpo JSON enviado, exatamente como saiu, junto com Estado, Tentativas, Código HTTP, Duração, Erro e Pedido (o request_id). A resposta do seu servidor não é guardada: só o código HTTP.
Catálogo de eventos
A lista oficial e sempre atual é a de GET /api/v1/webhooks/event-kinds, que também alimenta o seletor de eventos da tela. Os eventos abaixo são os que o NearOne Trust emite hoje.
Canal de denúncias e ouvidoria
| Evento | Quando acontece |
|---|---|
reporting.case.received | Um relato foi registrado (pelo canal público ou pela equipe). |
reporting.case.assigned | O caso ganhou um responsável ou o responsável foi trocado. |
reporting.case.unassigned | O caso ficou sem responsável. |
reporting.case.stage_changed | O caso mudou de etapa no fluxo de tratamento. |
reporting.case.closed | O caso foi encerrado. |
reporting.case.reopened | O caso foi reaberto. |
reporting.case.reporter_replied | Quem relatou enviou uma nova mensagem pelo acompanhamento. |
reporting.case.staff_replied | A equipe enviou uma mensagem pública a quem relatou (notas internas não geram evento). |
reporting.case.sla_at_risk | O prazo do caso está perto do fim. |
reporting.case.sla_overdue | O prazo do caso venceu. |
reporting.automation.firedAs automações do canal (em Canal e ouvidoria › Automações; veja também Implantação) têm o passo Chamar webhook, que envia o evento reporting.automation.fired para um webhook escolhido no passo, sem que ele precise estar inscrito. O corpo é o mesmo de um evento de caso, com dois campos a mais em data: automation_id e automation_name. As mesmas regras de caso protegido valem aqui. Use quando quiser condições finas (por exemplo, "só casos urgentes da empresa X") sem filtrar no seu lado.
Cadastros e configuração da organização
Estes eventos acompanham mudanças administrativas. O data traz poucos dados da mudança e muitas vezes é {}. Alguns exemplos: membership.invited traz o email convidado; api_key.created traz o name e o prefix da chave (nunca o segredo); tag.assigned traz a lista tag_ids, com resource_type indicando o alvo (company ou demand) e resource_id o UUID dele. Consulte o recurso pela API quando precisar do estado completo.
| Evento | Quando acontece |
|---|---|
company.created / company.updated / company.deleted | Empresa cadastrada, alterada ou removida. |
company_contact.created / company_contact.updated / company_contact.deleted | Contato de empresa cadastrado, alterado ou removido. |
company_group.created / company_group.updated / company_group.deleted | Grupo de empresas criado, alterado ou apagado. |
membership.invited | Uma pessoa foi convidada para a organização. |
membership.invite_resent | O convite foi reenviado. |
membership.updated | Papéis, escopo de empresas ou outros dados do membro mudaram. |
membership.blocked / membership.unblocked | Membro bloqueado ou desbloqueado. |
membership.removed | Membro removido da organização. |
membership.left | O próprio membro saiu da organização. |
role.created / role.updated / role.deleted | Papel personalizado criado, renomeado ou removido. |
role.permissions_replaced | As permissões de um papel foram substituídas. |
group.created / group.updated / group.deleted | Grupo de membros criado, alterado ou removido. |
tag.created / tag.updated / tag.deleted | Etiqueta criada, alterada ou apagada. |
tag.assigned | As etiquetas de uma empresa ou de um caso mudaram. |
api_key.created / api_key.patched / api_key.revoked | Chave de API criada, alterada ou revogada. |
file.created / file.deleted | Arquivo da organização criado ou removido. |
organization.security_updated | A política de segurança da organização mudou (segundo fator, domínios, sessões). |
mcp.settings_updated | A configuração do MCP da organização mudou. |
O catálogo da API e o seletor da tela também listam eventos audience.*. Eles pertencem a um módulo que não é usado pelo NearOne Trust e não são emitidos na operação do canal: você pode ignorá-los.
Evento de teste: webhook.ping
O botão Enviar teste, na página do webhook (ou POST /api/v1/webhooks/{code}/test), envia um webhook.ping com data: {}, resource_type: "webhook", resource_id igual ao UUID do próprio webhook e uma única tentativa. Se falhar, a entrega fica com o estado failed (a tela mostra Falhou (nova tentativa agendada), mas um teste nunca é repetido sozinho: envie outro). Use para conferir URL, TLS, firewall e validação da assinatura antes de depender do webhook. O resultado aparece em Entregas e numa mensagem como "Teste entregue (HTTP 204, 38 ms)" ou "O teste falhou (HTTP 500)".
Validar a assinatura
Toda entrega é assinada com o segredo do webhook. Validar a assinatura garante duas coisas: que a chamada veio do NearOne Trust e que o corpo não foi alterado no caminho. Nunca processe um evento sem validar.
O cabeçalho tem este formato:
X-Sg-Signature: t=1763320330,v1=5d1c0f…a9
té o horário da assinatura, em segundos Unix.v1é o HMAC-SHA256, em hexadecimal minúsculo, calculado com o segredo do webhook sobre a string"<t>.<corpo>".- Durante uma troca de segredo, o cabeçalho traz dois
v1: um do segredo novo e outro do anterior (t=…,v1=…,v1=…).
Regras, em ordem:
- Leia o corpo exatamente como chegou (bytes crus). Não faça
JSON.parseseguido deJSON.stringify: qualquer reformatação muda a assinatura. - Separe
te todos os valoresv1do cabeçalho. - Recuse se
testiver a mais de 5 minutos do seu relógio (proteção contra repetição). - Calcule
HMAC-SHA256(segredo, "<t>.<corpo>")em hexadecimal. - Aceite se qualquer
v1for igual ao valor calculado, comparando em tempo constante. - Use
X-Sg-Delivery(ou oiddo corpo) para ignorar entregas repetidas.
Node.js (Express)
import crypto from "node:crypto";
import express from "express";
const SECRET = process.env.NEARONE_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;
export function verifySignature(rawBody, header, secret, now = Date.now() / 1000) {
if (!header) return false;
const pairs = header.split(",").map((part) => {
const i = part.indexOf("=");
return [part.slice(0, i), part.slice(i + 1)];
});
const t = pairs.find(([k]) => k === "t")?.[1];
const signatures = pairs.filter(([k]) => k === "v1").map(([, v]) => v);
if (!t || !/^\d+$/.test(t) || Math.abs(now - Number(t)) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.`)
.update(rawBody) // Buffer com os bytes exatos do corpo
.digest("hex");
const expectedBuf = Buffer.from(expected, "utf8");
return signatures.some((sig) => {
const sigBuf = Buffer.from(sig, "utf8");
return sigBuf.length === expectedBuf.length && crypto.timingSafeEqual(sigBuf, expectedBuf);
});
}
const app = express();
// express.raw mantém o corpo como Buffer, sem reformatar.
app.post("/hooks/nearone", express.raw({ type: "application/json" }), (req, res) => {
if (!verifySignature(req.body, req.get("X-Sg-Signature"), SECRET)) {
return res.status(401).send("assinatura inválida");
}
const event = JSON.parse(req.body.toString("utf8"));
// Responda rápido; processe em segundo plano (fila, job, etc.).
res.status(204).end();
queueMicrotask(() => handleEvent(req.get("X-Sg-Delivery"), event));
});
function handleEvent(deliveryId, event) {
console.log(deliveryId, event.kind, event.data);
}
app.listen(3000);
Python (FastAPI)
import hashlib
import hmac
import json
import os
import time
from fastapi import BackgroundTasks, FastAPI, Header, HTTPException, Request, Response
SECRET = os.environ["NEARONE_WEBHOOK_SECRET"] # whsec_...
TOLERANCE_SECONDS = 300
app = FastAPI()
def verify_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
if not header:
return False
pairs = [item.split("=", 1) for item in header.split(",") if "=" in item]
timestamp = next((value for key, value in pairs if key == "t"), "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
return False
expected = hmac.new(
secret.encode("utf-8"),
timestamp.encode("ascii") + b"." + raw_body,
hashlib.sha256,
).hexdigest()
return any(hmac.compare_digest(value, expected) for key, value in pairs if key == "v1")
@app.post("/hooks/nearone", status_code=204)
async def receive(
request: Request,
background: BackgroundTasks,
x_sg_signature: str | None = Header(default=None),
x_sg_delivery: str | None = Header(default=None),
) -> Response:
raw = await request.body() # bytes exatos, antes de qualquer parse
if not verify_signature(raw, x_sg_signature, SECRET):
raise HTTPException(status_code=401, detail="assinatura inválida")
event = json.loads(raw)
background.add_task(handle_event, x_sg_delivery, event)
return Response(status_code=204)
def handle_event(delivery_id: str | None, event: dict) -> None:
print(delivery_id, event["kind"], event["data"])
Depois de publicar o receptor, use Enviar teste na página do webhook. Se a assinatura não bater, confira se você está usando o corpo cru e o segredo completo (incluindo o prefixo whsec_).
Entregas, novas tentativas e pausa automática
Uma entrega é considerada entregue quando o seu endpoint responde com qualquer código 2xx em até 10 segundos (o limite inclui a resolução de DNS e a conexão). Qualquer outra coisa conta como falha: código 3xx, 4xx ou 5xx, tempo esgotado, erro de TLS ou de conexão.
| Estado na tela | Valor na API | O que significa |
|---|---|---|
| Na fila | pending | Aguardando envio. |
| Entregue | delivered | O endpoint respondeu 2xx. |
| Falhou (nova tentativa agendada) | failed | A tentativa falhou e outra já está agendada. |
| Esgotada | exhausted | Não haverá novas tentativas automáticas. |
Novas tentativas. Uma entrega tem até 8 tentativas. A espera entre elas cresce de forma linear: cerca de 1 minuto depois da primeira falha, 2 minutos depois da segunda, 3 depois da terceira, e assim por diante. Do primeiro envio à última tentativa passa cerca de meia hora. Depois da oitava falha, a entrega fica Esgotada.
Falhas definitivas. Se o destino for recusado pela proteção de rede (por exemplo, o DNS passou a apontar para um IP privado), a entrega vai direto para Esgotada, sem chamada HTTP e sem novas tentativas.
Pausa automática. Se 10 entregas seguidas ficarem esgotadas, o webhook é pausado pelo sistema (estado Pausado por falhas) e todas as pessoas com permissão de gerir webhooks recebem um aviso na caixa de entrada do painel. Para voltar: confira o destino, use Enviar teste e clique em Retomar.
Enquanto um webhook está pausado (por você ou pelo sistema), nada novo entra na fila para ele, e os eventos desse período não são reenviados quando você retoma. Se o seu sistema não pode perder eventos, faça uma reconciliação pela API depois de retomar (por exemplo, liste os casos alterados desde a pausa). Enviar teste e Reenviar continuam funcionando com o webhook pausado, justamente para você testar antes de retomar.
Reenviar uma entrega
Em Entregas, abra uma entrega com estado Falhou (nova tentativa agendada) ou Esgotada e clique em Reenviar. O reenvio:
- faz uma única tentativa (sem novas tentativas automáticas se falhar);
- usa o mesmo
X-Sg-Deliverye o mesmoidde evento no corpo, com uma assinatura nova (novot); - aparece marcado como Reenvio manual na lista;
- se falhar, a entrega volta a Esgotada e não conta para a pausa automática.
Pela API: POST /api/v1/webhooks/{code}/deliveries/{delivery_id}/redeliver (veja Redeliver). Para listar entregas use List Deliveries, que aceita filtros como {"status": "exhausted"}.
| Ação | Limite por webhook |
|---|---|
| Enviar teste | 20 por hora |
| Reenviar | 120 por hora |
Acima do limite a API responde 429 com o cabeçalho Retry-After.
Trocar o segredo sem perder entregas
Troque o segredo periodicamente ou sempre que suspeitar de vazamento. Na página do webhook, clique em Trocar segredo e confirme.
- O novo segredo aparece uma única vez. Copie-o.
- Durante as próximas 24 horas, cada entrega leva duas assinaturas
v1: a do segredo novo e a do anterior. A tela mostra "Troca de segredo em andamento" com a data de término. - Atualize o segredo no seu receptor quando for conveniente. Como o receptor aceita qualquer
v1válido, nenhuma entrega é perdida durante a troca. - Depois de 24 horas, só o segredo novo assina.
Se o seu receptor guarda os dois segredos durante a janela, tente validar com cada um. Com o código desta página isso já funciona, porque ele aceita qualquer v1 que confira com o segredo configurado.
Outras ações na página do webhook
| Ação | O que faz |
|---|---|
| Editar | Muda o nome, a URL ou os eventos. O segredo continua o mesmo. |
| Pausar / Retomar | Interrompe ou retoma o envio. Retomar zera a contagem de falhas. |
| Receber aviso de casos protegidos | Liga ou desliga a marca {"protected": true} para eventos de casos protegidos. |
| Trocar segredo | Gera um segredo novo; o anterior vale por 24 horas. |
| Enviar teste | Envia um webhook.ping com uma tentativa. |
| Revogar | Desliga o webhook para sempre. Entregas pendentes deixam de ser enviadas. Para voltar a receber, crie outro. |
Criar, editar, pausar, retomar, ligar ou desligar o aviso de casos protegidos, trocar o segredo, reenviar e revogar ficam registrados na auditoria da organização. O teste aparece só na lista de Entregas, marcado como Teste.
Boas práticas no receptor
Responda rápido, processe depois
Você tem 10 segundos. Valide a assinatura, grave o evento numa fila ou tabela e responda 204 (ou 200). Faça chamadas à API, integrações com outros sistemas e qualquer coisa demorada depois de responder.
Seja idempotente
Uma mesma entrega pode chegar mais de uma vez: por exemplo, quando o seu servidor processou o evento mas a resposta não chegou a tempo, ou quando alguém clica em Reenviar. Proteja-se assim:
- Guarde o
X-Sg-Deliveryde cada entrega processada (uma tabela com chave única basta). - Se a entrega já existe, responda
2xxe não faça nada. - Se você tem mais de um webhook apontando para o mesmo sistema, use o
iddo corpo (o id do evento), que é o mesmo nas entregas para endpoints diferentes.
CREATE TABLE nearone_webhook_deliveries (
delivery_id uuid PRIMARY KEY,
event_id uuid NOT NULL,
kind text NOT NULL,
received_at timestamptz NOT NULL DEFAULT now()
);
-- INSERT ... ON CONFLICT (delivery_id) DO NOTHING; se não inseriu, já foi processado.
Não confie na ordem
Use os eventos como um sinal de que algo mudou e consulte o estado atual na API quando a decisão depender dele. Exemplo: ao receber reporting.case.stage_changed, busque o caso pelo case_code e use a etapa que a API devolver.
Proteja o endpoint
- Exija HTTPS com certificado válido.
- Recuse requisições sem assinatura válida com
401, sem detalhar o motivo. - Guarde o segredo num cofre de segredos ou variável de ambiente, nunca no código.
- Não registre o corpo completo em logs públicos; ele contém códigos de casos.
Ler o caso a partir do evento
O evento diz o que aconteceu e qual caso. Para ler o caso, use o case_code com uma chave de API que tenha permissão de leitura de casos:
curl https://api.trust.nearone.com.br/api/v1/requests/demands/8WG8 \
-H "Authorization: Bearer $NEARONE_API_KEY"
A API aplica as permissões e o escopo de empresas da chave, e um caso protegido só aparece para quem tem concessão nominal. Veja Get Demand e, para criar e usar chaves, Autenticação. Receitas prontas estão em Exemplos.
Problemas comuns
| Sintoma | Causa provável | O que fazer |
|---|---|---|
Toda entrega falha com HTTP 301 ou 302 | A URL redireciona (por exemplo, sem barra final ou http→https). | Cadastre a URL final; redirecionamentos não são seguidos. |
Erro webhook_url_invalid ao salvar | Host local, IP privado, usuário/senha ou fragmento na URL. | Use um endereço público https://. |
Erro webhook_url_insecure | URL http://. | Use https://. |
TimeoutError, ConnectTimeout, ReadTimeout ou ConnectError em Erro | O endpoint demorou mais de 10 s ou o firewall bloqueia. | Responda antes de processar; libere a origem no firewall. |
| Assinatura nunca confere | O corpo foi reformatado antes do cálculo, ou o segredo está incompleto. | Calcule sobre os bytes crus e use o segredo inteiro, com whsec_. |
| Assinatura falha só em alguns servidores | Relógio do servidor fora de hora. | Sincronize com NTP; a tolerância é de 5 minutos. |
| Webhook aparece como Pausado por falhas | 10 entregas seguidas esgotaram. | Corrija o destino, Enviar teste, Retomar e reconcilie pela API. |
| Não chegam eventos de alguns casos | São casos protegidos. | Ative Receber aviso de casos protegidos, se fizer sentido (só a marca chega). |
Referência da API
| Operação | Rota |
|---|---|
| Listar tipos de evento | GET /api/v1/webhooks/event-kinds |
| Criar webhook | POST /api/v1/webhooks |
| Listar webhooks | GET /api/v1/webhooks |
| Ver webhook | GET /api/v1/webhooks/{code} |
| Alterar webhook | PATCH /api/v1/webhooks/{code} (name, url, event_kinds, include_protected) |
| Pausar / Retomar | POST /api/v1/webhooks/{code}/pause · /resume |
| Trocar segredo | POST /api/v1/webhooks/{code}/rotate-secret |
| Enviar teste | POST /api/v1/webhooks/{code}/test (202) |
| Listar entregas | GET /api/v1/webhooks/{code}/deliveries |
| Ver entrega | GET /api/v1/webhooks/{code}/deliveries/{delivery_id} |
| Reenviar entrega | POST /api/v1/webhooks/{code}/deliveries/{delivery_id}/redeliver (202) |
| Revogar | POST /api/v1/webhooks/{code}/revoke (204) |