Webhook › Testar
Manda agora um evento de teste ao webhook e diz o que ele respondeu
POST/v1/webhook-endpoint/ping
Sem type, um ping. Com type, um evento público (shipment.dispatch, pix.paid…) com o data de exemplo do contrato. O corpo leva test: true e a assinatura é a de sempre: é o jeito de provar o seu receptor sem esperar o galpão. Não grava fato nem entrega, e não muda nada na empresa.
Ação da chave:
integration.webhook.pingQuem cria a chave escolhe as ações que ela abre; sem esta, a rota recusa com api_key_action_not_granted.
Corpo
type string
ping (padrão) ou um evento público, com o nome do contrato.
Devolve
O data do envelope { ok, data, error, error_code, field, trace_id }:
delivered boolean OBRIGATÓRIO
O endpoint respondeu 2xx.
duration_ms integer OBRIGATÓRIO
error string, ou nulo OBRIGATÓRIO
event_id uuid OBRIGATÓRIO
status integer, ou nulo OBRIGATÓRIO
O status HTTP da resposta; nulo quando nem respondeu.
type string OBRIGATÓRIO
O que foi mandado: ping ou o evento pedido.
Recusas
HTTP 400 · Pedido mal formado
version_unknown HTTP 400A Kernos-Version pedida não existe. Use uma das versões declaradas no cabeçalho, ou não o mande.HTTP 401 · Sem credencial válida
api_key_expired HTTP 401A chave venceu. Gire a chave no painel e use a nova.api_key_wrong_environment HTTP 401A chave é do outro ambiente: ksk_test_ vai em https://stag.kernos.com.br, ksk_live_ em https://api.kernos.com.br.unauthenticated HTTP 401Credencial ausente, inválida ou expirada.HTTP 403 · Sem permissão
agent_token_out_of_scope HTTP 403O token de agente (kat_) só vale na porta MCP. Para a API, use o token de sessão ou uma chave de integração.api_key_action_not_granted HTTP 403A chave não tem esta ação. Edite as ações da chave no painel.api_key_out_of_scope HTTP 403A chave só vale nas rotas do contrato público.depot_out_of_reach HTTP 403Quem chama não alcança o CD deste objeto. Peça alcance ao CD ou use outra credencial.forbidden_role HTTP 403O papel de quem chama nesta empresa não permite esta ação.module_not_subscribed HTTP 403A empresa não assina o módulo desta rota.tenant_mismatch HTTP 403A credencial não pertence à empresa do endereço chamado.tenant_unavailable HTTP 403A empresa está indisponível no momento.HTTP 404 · Não encontrado
not_found HTTP 404Não existe objeto com esse identificador nesta empresa.HTTP 422 · Não processável
invalid_event_type HTTP 422Um dos tipos não é um evento público. Use os nomes do contrato, separados por vírgula (shipment.dispatch,pix.paid).HTTP 429 · Muitos pedidos
rate_limited HTTP 429Muitos pedidos por segundo com esta chave. Espere o Retry-After, em segundos, e tente de novo.HTTP 503 ·
vault_unavailable HTTP 503O cofre do servidor está fechado agora e nada foi guardado. Tente de novo em alguns minutos.curlNodePythonPHPJavaC#GoRust
Manda agora um evento de teste ao webhook e diz o que ele respondeu
curl -X POST "https://stag.kernos.com.br/v1/webhook-endpoint/ping" \
-H "Authorization: Bearer ksk_test_…" \
-H "Kernos-Version: 2026-10-03" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "type": "ping" }'Manda agora um evento de teste ao webhook e diz o que ele respondeu
import { Kernos } from '@kernosbr/kernos'
const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.integrationWebhook.ping({ type: 'ping' })Manda agora um evento de teste ao webhook e diz o que ele respondeu
import os
from kernos import Kernos
kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.integration_webhook.ping({"type": "ping"})Manda agora um evento de teste ao webhook e diz o que ele respondeu
<?php
$kernos = new Kernos\Kernos(getenv('KERNOS_API_KEY'));
$result = $kernos->integrationWebhook->ping(['type' => 'ping']);Manda agora um evento de teste ao webhook e diz o que ele respondeu
Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.integrationWebhook().ping(Map.of("type", "ping"));Manda agora um evento de teste ao webhook e diz o que ele respondeu
var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.IntegrationWebhook.PingAsync(new { type = "ping" });Manda agora um evento de teste ao webhook e diz o que ele respondeu
client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.IntegrationWebhook.Ping(ctx, map[string]any{"type": "ping"})Manda agora um evento de teste ao webhook e diz o que ele respondeu
let kernos = Kernos::new(&std::env::var("KERNOS_API_KEY")?)?;
let result = kernos.integration_webhook().ping(&json!({ "type": "ping" }), None)?;Resposta · 200 (a forma, sem dado real)
{
"ok": true,
"data": {
"delivered": true,
"duration_ms": 0,
"error": "…",
"event_id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
"status": 0,
"type": "…"
},
"error": null,
"error_code": null,
"field": null,
"trace_id": null
}Ambiente
ksk_test_ fala com https://stag.kernos.com.br; ksk_live_, com https://api.kernos.com.br. O prefixo da chave escolhe o endereço.