📣 Webhooks de Saída
O Nexus chama a URL do seu sistema quando uma tarefa é criada, muda, troca de status ou de
responsável, ou recebe um comentário. É o caminho de volta da API de Integração:
o ERP cria a tarefa pela API e fica sabendo pelo webhook quando a equipe a conclui, sem perguntar
de tempos em tempos. Issue #75.
Em um minuto
|
|
| Onde cadastrar |
Configurações do workspace → Integrações → Webhooks de saída (Owner ou Admin) |
| O que informar |
Nome, URL https pública e os eventos que interessam |
| Segredo |
Gerado pelo Nexus (whsec_...), mostrado uma vez; assina cada chamada |
| Entrega |
POST com JSON; 2xx conta como entregue |
| Tentativas |
1, 5 e 30 minutos depois de cada falha; a quarta falha encerra |
| Proteção |
50 falhas definitivas seguidas pausam o webhook e avisam os administradores |
| Histórico |
Últimas 20 entregas na tela, com "reenviar"; guardadas por 30 dias |
| Planos |
Os mesmos da API: Pro e Business |
Eventos
type |
Quando |
Traz em previous |
task.created |
Tarefa criada (tela, API ou MCP) |
nada |
task.status_changed |
Mudou de status (painel da tarefa, arrastar no quadro, API) |
status anterior |
task.assignee_changed |
Mudou o responsável |
assignee anterior (ou null) |
task.updated |
Mudou título, descrição, tipo, prioridade, datas ou referência externa |
só os campos que mudaram, com o valor anterior |
comment.created |
Comentário novo na tarefa |
nada; o comentário vem em comment |
ping |
Botão "Enviar teste" |
nada |
Uma mesma edição pode gerar mais de um evento: mover para "Feito" e trocar o responsável na
mesma tela gera task.status_changed e task.assignee_changed, cada um com o próprio id.
Corpo
{
"id": "0d4b...",
"type": "task.status_changed",
"occurredAtUtc": "2026-11-17T14:03:11Z",
"workspaceId": "7c1e...",
"actor": { "id": "...", "name": "Ana Souza", "email": "[email protected]" },
"task": {
"id": "9b2e...",
"code": "TASK-12",
"title": "Separar pedido 1001",
"status": { "id": "...", "name": "Feito", "category": "Done", "isDefault": false },
"assignee": { "id": "...", "name": "Ana Souza", "email": "[email protected]" },
"externalReference": "PEDIDO-1001",
"url": "https://nexus.aamora.com.br/lists/4f1c.../list"
},
"previous": { "status": { "id": "...", "name": "Fazendo", "category": "InProgress" } },
"comment": null
}
task é a mesma tarefa da Referência da API. Use
externalReference para achar o registro no seu sistema.
actor é quem fez a mudança. Vem null quando a mudança veio de um arrasto no quadro, e com o
nome da integração quando veio pela API ("Integração \"ERP\"").
id é o id do evento. Se o Nexus reenviar (tentativa ou "reenviar" na tela), o id é o mesmo:
use-o para não processar duas vezes.
Cabeçalhos
| Cabeçalho |
Conteúdo |
X-Nexus-Event |
O type do evento |
X-Nexus-Delivery |
Id desta entrega (muda a cada tentativa; o id do corpo não) |
X-Nexus-Signature |
sha256=<HMAC-SHA256 do corpo, em hexadecimal, com o segredo> |
User-Agent |
Nexus-Webhooks/1.0 |
Content-Type |
application/json; charset=utf-8 |
Validar a assinatura
Calcule o HMAC-SHA256 do corpo bruto (os bytes exatamente como chegaram, antes de qualquer
parse) com o segredo, e compare com o cabeçalho em tempo constante. Rejeite com 401 quando não
bater.
C# (ASP.NET Core)
app.MapPost("/nexus/webhook", async (HttpRequest request) =>
{
using var reader = new StreamReader(request.Body);
var body = await reader.ReadToEndAsync();
var secret = Environment.GetEnvironmentVariable("NEXUS_WEBHOOK_SECRET")!;
var expected = "sha256=" + Convert.ToHexStringLower(
HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(body)));
var received = request.Headers["X-Nexus-Signature"].ToString();
if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(received)))
{
return Results.Unauthorized();
}
var evt = JsonSerializer.Deserialize<JsonElement>(body);
if (evt.GetProperty("type").GetString() == "task.status_changed"
&& evt.GetProperty("task").GetProperty("status").GetProperty("category").GetString() == "Done")
{
var os = evt.GetProperty("task").GetProperty("externalReference").GetString();
// fechar a OS no ERP
}
return Results.NoContent(); // responda rápido; faça o trabalho pesado numa fila
});
Python (Flask)
import hmac, hashlib, os
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["NEXUS_WEBHOOK_SECRET"].encode()
@app.post("/nexus/webhook")
def nexus_webhook():
body = request.get_data() # bytes crus, antes do JSON
expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Nexus-Signature", "")):
abort(401)
event = request.get_json()
if event["type"] == "task.status_changed" and event["task"]["status"]["category"] == "Done":
erp.fechar_os(event["task"]["externalReference"])
return "", 204
Boas práticas do receptor
- Responda em menos de 10 segundos, de preferência
204 na hora, e processe depois. Passou de
10 s, o Nexus conta como falha e tenta de novo.
- Trate como "pelo menos uma vez". Uma tentativa pode ter chegado e a resposta se perdido;
guarde o
id do evento e ignore repetidos.
- Não confie na ordem. Dois eventos próximos podem chegar trocados; use
occurredAtUtc
quando a ordem importar.
- URL pública e
https. O Nexus recusa http, localhost e endereços de rede interna. Em
desenvolvimento, o webhook.site serve para ver o que chega; para testar o
seu próprio código local, use um túnel (ngrok, Cloudflare Tunnel).
- Trocar o segredo: exclua o webhook e cadastre de novo. O novo segredo aparece uma vez.
Quando algo dá errado
| Na tela |
O que quer dizer |
| "Tentando de novo (2 de 4)" |
Falhou duas vezes; a próxima tentativa já está agendada |
| "Falhou (4 tentativas)" |
Desistiu desta entrega; "Reenviar" cria uma nova |
| "Pausado · 50 falhas seguidas" |
O Nexus parou de chamar; conserte a URL e clique em "Reativar" (zera a contagem) |
| Resposta "Sem resposta em 10 segundos" |
O seu endpoint demorou; responda antes e processe depois |