Pular para o conteúdo principal

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.
Referências, nunca conteúdo

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​

  1. Algo acontece na organização e o evento entra numa fila de entregas, uma entrega por endpoint inscrito naquele tipo de evento.
  2. Um processo em segundo plano faz um POST com o corpo JSON assinado para a URL do endpoint.
  3. O seu sistema confere a assinatura, responde rapidamente com um código 2xx e processa o evento depois.
  4. Se precisar de detalhes, o seu sistema consulta a API usando o código do caso que veio no evento.
Os eventos do canal chegam logo depois do fato

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.

Tela Webhooks do painel do NearOne Trust, no menu Integração, ainda sem nenhum endpoint cadastrado, com a busca e o botão Novo webhook.
Sem webhooks, a tela mostra Nenhum webhook e o botão Novo webhook. Depois do primeiro cadastro, a lista traz as colunas Nome, URL, Estado (Ativo, Pausado, Pausado por falhas ou Revogado) e Criado. Dados fictícios da organização de demonstração.
  1. Clique em Novo webhook.
  2. Preencha Nome: identifique o sistema que vai receber os eventos (por exemplo, "ERP de produção"). Até 120 caracteres.
  3. 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.
  4. 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.
  5. Clique em Criar webhook.
  6. 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.

Marque só o que você usa

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.

Regras da URL
  • Só https. Endereços http, localhost, domínios .local e IPs privados, de loopback ou reservados são recusados (erro webhook_url_invalid ou webhook_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/302 conta 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çalhoExemploPara que serve
Content-Typeapplication/jsonO corpo é JSON.
User-AgentNearOneTrust-Webhooks/1.0Identifica a origem da chamada.
X-Sg-Eventreporting.case.receivedO tipo do evento. Útil para rotear sem abrir o corpo.
X-Sg-Delivery5f0c… (UUID)O identificador desta entrega. É o mesmo em todas as tentativas e no reenvio manual.
X-Sg-Signaturet=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"
}
}
CampoDescrição
idIdentificador do evento. Se o mesmo evento for entregue a dois endpoints seus, os dois recebem o mesmo id.
kindTipo do evento (igual ao cabeçalho X-Sg-Event).
created_atQuando o evento foi registrado (ISO 8601, UTC).
organization_idA organização em que o evento aconteceu.
resource_typeTipo do recurso: reporting_case para casos, company, org_membership, role etc. para os demais.
resource_idUUID do recurso. É null para eventos de caso protegido.
actor_typeQuem originou: system nos eventos de caso; identity (pessoa) ou api_key nos eventos de cadastro.
request_idIdentificador da requisição que originou o evento, quando houver. Útil para cruzar com a auditoria e com o suporte.
dataDados 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.*)​

CampoExemploSignificado
case_code8WG8Có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.
channeldenunciasIdentificador (slug) do canal pelo qual o relato chegou.
company_codePE57Código da empresa do caso.
typeassedio_moralChave da categoria do relato.
phasein_progressFase do caso: pending, in_progress, waiting, scheduled ou closed.
stage_keyreceivedChave da etapa atual no fluxo de tratamento.
prioritynormalPrioridade: normal, high ou urgent.
sla_stateat_riskSituação do prazo: on_track, at_risk, overdue, paused, met, missed ou none (sem prazo).
Casos protegidos

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​

EventoQuando acontece
reporting.case.receivedUm relato foi registrado (pelo canal público ou pela equipe).
reporting.case.assignedO caso ganhou um responsável ou o responsável foi trocado.
reporting.case.unassignedO caso ficou sem responsável.
reporting.case.stage_changedO caso mudou de etapa no fluxo de tratamento.
reporting.case.closedO caso foi encerrado.
reporting.case.reopenedO caso foi reaberto.
reporting.case.reporter_repliedQuem relatou enviou uma nova mensagem pelo acompanhamento.
reporting.case.staff_repliedA equipe enviou uma mensagem pública a quem relatou (notas internas não geram evento).
reporting.case.sla_at_riskO prazo do caso está perto do fim.
reporting.case.sla_overdueO prazo do caso venceu.
Evento enviado por automação: reporting.automation.fired

As 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.

EventoQuando acontece
company.created / company.updated / company.deletedEmpresa cadastrada, alterada ou removida.
company_contact.created / company_contact.updated / company_contact.deletedContato de empresa cadastrado, alterado ou removido.
company_group.created / company_group.updated / company_group.deletedGrupo de empresas criado, alterado ou apagado.
membership.invitedUma pessoa foi convidada para a organização.
membership.invite_resentO convite foi reenviado.
membership.updatedPapéis, escopo de empresas ou outros dados do membro mudaram.
membership.blocked / membership.unblockedMembro bloqueado ou desbloqueado.
membership.removedMembro removido da organização.
membership.leftO próprio membro saiu da organização.
role.created / role.updated / role.deletedPapel personalizado criado, renomeado ou removido.
role.permissions_replacedAs permissões de um papel foram substituídas.
group.created / group.updated / group.deletedGrupo de membros criado, alterado ou removido.
tag.created / tag.updated / tag.deletedEtiqueta criada, alterada ou apagada.
tag.assignedAs etiquetas de uma empresa ou de um caso mudaram.
api_key.created / api_key.patched / api_key.revokedChave de API criada, alterada ou revogada.
file.created / file.deletedArquivo da organização criado ou removido.
organization.security_updatedA política de segurança da organização mudou (segundo fator, domínios, sessões).
mcp.settings_updatedA configuração do MCP da organização mudou.
observação

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:

  1. Leia o corpo exatamente como chegou (bytes crus). Não faça JSON.parse seguido de JSON.stringify: qualquer reformatação muda a assinatura.
  2. Separe t e todos os valores v1 do cabeçalho.
  3. Recuse se t estiver a mais de 5 minutos do seu relógio (proteção contra repetição).
  4. Calcule HMAC-SHA256(segredo, "<t>.<corpo>") em hexadecimal.
  5. Aceite se qualquer v1 for igual ao valor calculado, comparando em tempo constante.
  6. Use X-Sg-Delivery (ou o id do corpo) para ignorar entregas repetidas.

Node.js (Express)​

receptor-webhook.js
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)​

receptor_webhook.py
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"])
Teste com o botão Enviar teste

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 telaValor na APIO que significa
Na filapendingAguardando envio.
EntreguedeliveredO endpoint respondeu 2xx.
Falhou (nova tentativa agendada)failedA tentativa falhou e outra já está agendada.
EsgotadaexhaustedNã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.

O que acontece durante uma pausa não é entregue depois

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-Delivery e o mesmo id de evento no corpo, com uma assinatura nova (novo t);
  • 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çãoLimite por webhook
Enviar teste20 por hora
Reenviar120 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.

  1. O novo segredo aparece uma única vez. Copie-o.
  2. 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.
  3. Atualize o segredo no seu receptor quando for conveniente. Como o receptor aceita qualquer v1 válido, nenhuma entrega é perdida durante a troca.
  4. Depois de 24 horas, só o segredo novo assina.
Receptor preparado para rotação

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çãoO que faz
EditarMuda o nome, a URL ou os eventos. O segredo continua o mesmo.
Pausar / RetomarInterrompe ou retoma o envio. Retomar zera a contagem de falhas.
Receber aviso de casos protegidosLiga ou desliga a marca {"protected": true} para eventos de casos protegidos.
Trocar segredoGera um segredo novo; o anterior vale por 24 horas.
Enviar testeEnvia um webhook.ping com uma tentativa.
RevogarDesliga 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:

  1. Guarde o X-Sg-Delivery de cada entrega processada (uma tabela com chave única basta).
  2. Se a entrega já existe, responda 2xx e não faça nada.
  3. Se você tem mais de um webhook apontando para o mesmo sistema, use o id do 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​

SintomaCausa provávelO que fazer
Toda entrega falha com HTTP 301 ou 302A 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 salvarHost local, IP privado, usuário/senha ou fragmento na URL.Use um endereço público https://.
Erro webhook_url_insecureURL http://.Use https://.
TimeoutError, ConnectTimeout, ReadTimeout ou ConnectError em ErroO endpoint demorou mais de 10 s ou o firewall bloqueia.Responda antes de processar; libere a origem no firewall.
Assinatura nunca confereO 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 servidoresRelógio do servidor fora de hora.Sincronize com NTP; a tolerância é de 5 minutos.
Webhook aparece como Pausado por falhas10 entregas seguidas esgotaram.Corrija o destino, Enviar teste, Retomar e reconcilie pela API.
Não chegam eventos de alguns casosSão casos protegidos.Ative Receber aviso de casos protegidos, se fizer sentido (só a marca chega).

Referência da API​

OperaçãoRota
Listar tipos de eventoGET /api/v1/webhooks/event-kinds
Criar webhookPOST /api/v1/webhooks
Listar webhooksGET /api/v1/webhooks
Ver webhookGET /api/v1/webhooks/{code}
Alterar webhookPATCH /api/v1/webhooks/{code} (name, url, event_kinds, include_protected)
Pausar / RetomarPOST /api/v1/webhooks/{code}/pause · /resume
Trocar segredoPOST /api/v1/webhooks/{code}/rotate-secret
Enviar testePOST /api/v1/webhooks/{code}/test (202)
Listar entregasGET /api/v1/webhooks/{code}/deliveries
Ver entregaGET /api/v1/webhooks/{code}/deliveries/{delivery_id}
Reenviar entregaPOST /api/v1/webhooks/{code}/deliveries/{delivery_id}/redeliver (202)
RevogarPOST /api/v1/webhooks/{code}/revoke (204)