Enviar informação ao Oráculo
Para qualquer plataforma que consiga fazer um pedido HTTP. Não é preciso instalar nada nem configurar regras no Oráculo: o teu sistema diz o que quer mostrar (abrir ou fechar uma pendência ou um incidente, ou registar uma actividade) e o Oráculo mostra-o no painel.
Contrato oraculo.event.v1.
Antes de começar
Precisas de dois valores, que quem administra o Oráculo te dá depois de criar a ligação (próximo passo):
| Valor | Exemplo | Nota |
|---|---|---|
| URL do webhook | https://oraculo.exemplo.org/v1/hooks/uJyRbKodieoLHXTC | Cada integração tem o seu. |
| Credencial | orc_wh_4f2a… | Só aparece uma vez. Se se perder, gera-se outra e a anterior deixa de funcionar. |
Trata a credencial como uma palavra-passe: guarda-a numa variável de ambiente ou num cofre, nunca no código nem num repositório.
Criar a organização e a ligação
Faz-se uma vez, na aplicação do Oráculo:
- Cria a organização em Criar a minha organização, ou pede ao administrador da tua.
- Instala a aplicação (Windows ou macOS). A ligação para a transferir está na página inicial.
- Abre-a, escolhe Configurar esta estação e entra com o email e a palavra-passe do passo 1.
- Em Configurações > Projectos, cria um projecto. O nome é o que aparece no ecrã.
- Em Configurações > Integrações, escolhe o projecto e toca em Nova integração. Deixa Contrato Oráculo (recomendado), dá um nome e cria.
- Copia o URL do webhook e a credencial. A credencial só aparece agora. No separador Ligação há também um «Código pronto» em PHP, C#, JavaScript, PowerShell e curl, já com o URL desta integração.
Os contadores não se declaram: nascem com o primeiro aviso, com o nome e o ícone que o aviso trouxer. Depois podes renomeá-los no separador Contadores.
O pedido
POST {URL do webhook}
Authorization: Bearer {credencial}
Content-Type: application/json- A credencial também pode ir no cabeçalho
X-Oraculo-Key: {credencial}. - O corpo é um objecto JSON (não uma lista), até 256 KiB, em UTF-8.
- O
Content-Typetem de serapplication/json. - Usa um limite de tempo curto (3 s) e nunca deixes uma falha do Oráculo estragar o pedido do teu utilizador (ver Boas práticas).
Os três tipos de aviso
Abrir uma pendência ou um incidente
{
"eventId": "denuncia-142-criada",
"kind": "pending",
"state": "open",
"counter": "denuncias",
"label": "Denúncias por responder",
"icon": "flag",
"recordId": "142",
"title": "Denúncia #142"
}Fechar o mesmo registo
Mesmo counter e mesmo recordId, com "state": "resolved":
{
"eventId": "denuncia-142-respondida-9",
"kind": "pending",
"state": "resolved",
"counter": "denuncias",
"recordId": "142"
}Registar uma actividade
Não tem estado nem contador. Aparece na lista de actividade recente:
{
"eventId": "produtor-5521-novo",
"kind": "activity",
"label": "Novo produtor",
"icon": "user",
"company": "AgroSul",
"title": "Produtor registado em Chókwè"
}Os campos
| Campo | Quando | Regra |
|---|---|---|
eventId | sempre | Identifica este acontecimento, estável e único (até 200 caracteres). Se reenviares o mesmo acontecimento, usa o mesmo eventId: o Oráculo ignora a repetição. |
kind | sempre | pending (pendência), incident (incidente) ou activity (actividade recente). |
state | pending, incident | open ou resolved. |
counter | pending, incident | Chave do contador: minúsculas, números, - e _, até 60 caracteres (denuncias, armazem-offline). Um contador é só de pendências ou só de incidentes. |
recordId | pending, incident | Identifica o registo (até 200). Abrir e fechar o mesmo registo usam o mesmo recordId. |
label | recomendado | Nome mostrado no painel (até 60). Em activity é o nome da actividade. |
icon | não | flag question message warehouse sprout clipboard alert bell truck user box bolt check clock |
severity | não | critical, high, medium, low ou info. Por omissão: incidente high, pendência medium. Um incidente critical ou high põe o cartão do projecto em estado crítico. |
title | não | Texto do cartão (até 300). Só referências, nunca conteúdo sensível. |
company | não | Agrupa o painel por empresa (nos projectos que o usam). |
occurredAt | não | Data do acontecimento, ISO 8601 (2026-11-14T08:12:00Z). |
version | recomendado | Inteiro crescente, até 15 dígitos (por exemplo milissegundos desde 1970). |
url | não | Ligação http(s) para abrir o registo no teu sistema (fica atrás do teu login). |
contract | não | oraculo.event.v1. Com outro valor o evento é recusado. |
Campos desconhecidos (por exemplo um meta teu) são ignorados e, por omissão, não são guardados.
Contadores
Nascem com o primeiro aviso que os menciona, com o label e o icon desse aviso. Não há nada para declarar antes. Depois, o administrador pode renomear, mudar o ícone e reordenar no Oráculo; o que ele editar prevalece sobre o que os avisos seguintes trouxerem.
O que o Oráculo responde
| Código | Significado | O que fazer |
|---|---|---|
202 | Aceite. O campo outcome diz o efeito: opened, updated, resolved, activity ou ignored_stale. | Nada. |
200 com "status": "duplicate" | Já tinha recebido este eventId. | Nada: não conta duas vezes. |
401 invalid_webhook_credential | Credencial em falta, errada, revogada ou de outra integração. | Confirmar a credencial. |
403 integration_disabled | A integração está desligada no Oráculo. | Pedir ao administrador que a ligue. |
415 / 400 invalid_json | Não é application/json, ou o JSON está partido, ou não é um objecto. | Corrigir o pedido. |
400 invalid_encoding | O corpo não é UTF-8 válido (acentos enviados em Latin-1). | Enviar o JSON em UTF-8. Ver a nota do curl no Windows, em Exemplos. |
413 payload_too_large | Corpo acima do limite. | Enviar menos. |
422 invalid_event | O evento tem erros. A mensagem lista todos de uma vez. | Corrigir (não repetir sem alterar). |
422 counter_kind_mismatch | O contador já existe como pendência e enviaste incidente (ou o contrário). | Usar outro counter ou corrigir o kind. |
5xx ou falha de rede | Problema temporário. | Repetir com o mesmo eventId. |
Exemplo de erro (422):
{ "statusCode": 422, "code": "invalid_event",
"message": "«state» tem de ser «open» ou «resolved». Falta «recordId»: liga a abertura e o fecho do mesmo registo." }Ordem e repetições
- Repetir é seguro. O mesmo
eventIdnunca conta duas vezes. - Ordem. Se dois avisos sobre o mesmo registo chegarem trocados, o Oráculo guarda o mais recente. Para decidir usa
version; se não houver,occurredAt; se também não houver, a ordem de chegada. Enviaversionsempre que puderes. - Fechar antes de abrir. Se o fecho chegar primeiro, fica registado e a abertura atrasada (mais antiga) é ignorada (
ignored_stale). - Reabrir. Um
openmais recente do que oresolvedreabre o mesmo registo. - Vários avisos do mesmo registo. Cada acontecimento tem o seu
eventId(denuncia-142-respondida-9,denuncia-142-respondida-10). Fechar um registo já fechado não muda nada.
Boas práticas
- Envia depois de a tua base de dados confirmar a alteração, nunca antes.
- Limite de tempo curto (3 s) e
try/catchà volta: uma falha do Oráculo não pode estragar o que o teu utilizador estava a fazer. - Regista a falha sem dados pessoais (por exemplo só o
eventId). - Repete só
5xxe falhas de rede, com o mesmoeventId. Não repitas4xx. - Não enviar conteúdo sensível: nem o texto de um relato, nem nome, e-mail, telefone, nem códigos de acompanhamento (funcionam como credenciais). Uma referência, um tipo, um distrito e as datas chegam.
- Não há limite de frequência nesta versão; se enviares muitos avisos por segundo, agrupa ou espaça os pedidos.
Testar sem gravar nada
Acrescenta o cabeçalho X-Oraculo-Dry-Run: 1. O Oráculo valida o evento e diz o que faria, sem criar contadores, sem gravar e sem avisar o painel:
curl -sS -X POST "$URL" \
-H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
-H "X-Oraculo-Dry-Run: 1" \
-d '{"eventId":"teste-1","kind":"pending","state":"open","counter":"denuncias","recordId":"1"}'{ "contract": "webhook.v1", "status": "dry_run",
"preview": { "explanation": "Abre uma pendência em «Denuncias» para o registo 1.", "errors": [] } }Se o evento tiver erros, a resposta é 422 com a lista, tal como num envio real. Na aplicação, o separador Testar da integração faz o mesmo com exemplos prontos.
Para um envio real, tira o cabeçalho. Em seguida confirma na aplicação, em Contadores e Entregas (cada aviso aparece com o efeito que teve), ou no painel.
Exemplos por linguagem
Substitui URL e CHAVE. Todos têm limite de 3 s e nunca lançam erros.
curl
curl -sS -m 3 -X POST "$URL" \
-H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
-d '{"eventId":"denuncia-142-criada","kind":"pending","state":"open","counter":"denuncias","label":"Denúncias por responder","icon":"flag","recordId":"142","title":"Denúncia #142"}'No Windows, o curl.exe envia em Latin-1 os acentos postos num argumento (-d '{"label":"Denúncias"}') e o Oráculo recusa o pedido com 400 invalid_encoding. Guarda o JSON num ficheiro UTF-8 e usa --data-binary @evento.json. Em Linux e macOS o exemplo de cima funciona tal como está.
JavaScript (Node 18 ou superior)
async function avisarOraculo(evento) {
try {
await fetch(process.env.ORACULO_URL, {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.ORACULO_CHAVE}` },
body: JSON.stringify({ contract: "oraculo.event.v1", version: Date.now(), ...evento }),
signal: AbortSignal.timeout(3000),
});
} catch (e) {
console.warn("Oráculo não recebeu o evento", evento.eventId);
}
}
await avisarOraculo({ eventId: "denuncia-142-criada", kind: "pending", state: "open",
counter: "denuncias", label: "Denúncias por responder", icon: "flag", recordId: "142", title: "Denúncia #142" });PowerShell
function Send-Oraculo([hashtable]$Evento) {
$corpo = @{ contract = 'oraculo.event.v1'; version = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() } + $Evento
try {
Invoke-RestMethod -Method Post -Uri $env:ORACULO_URL -TimeoutSec 3 `
-Headers @{ Authorization = "Bearer $env:ORACULO_CHAVE" } `
-ContentType 'application/json; charset=utf-8' `
-Body ([Text.Encoding]::UTF8.GetBytes(($corpo | ConvertTo-Json -Depth 5))) | Out-Null
} catch { Write-Warning "Oráculo não recebeu o evento $($Evento.eventId)" }
}
Send-Oraculo @{ eventId = 'denuncia-142-criada'; kind = 'pending'; state = 'open'; counter = 'denuncias'
label = 'Denúncias por responder'; icon = 'flag'; recordId = '142'; title = 'Denúncia #142' }Em PowerShell 5.1, envia o corpo em bytes UTF-8, como acima, para os acentos não se estragarem.
PHP / Laravel
// O URL e a credencial vêm de config/services.php:
// 'oraculo' => ['url' => env('ORACULO_URL'), 'chave' => env('ORACULO_CHAVE')]
// Não uses env() aqui: com `php artisan config:cache` devolve null.
function oraculo(array $evento): void
{
try {
\Illuminate\Support\Facades\Http::withToken(config('services.oraculo.chave'))
->acceptJson()->connectTimeout(2)->timeout(3)
->post(config('services.oraculo.url'), $evento + [
'contract' => 'oraculo.event.v1',
'version' => (int) floor(microtime(true) * 1000),
]);
} catch (\Throwable $e) {
\Log::warning('Oráculo não recebeu o evento', ['event_id' => $evento['eventId'] ?? null]);
}
}
oraculo(['eventId' => "denuncia-$id-criada", 'kind' => 'pending', 'state' => 'open',
'counter' => 'denuncias', 'label' => 'Denúncias por responder', 'icon' => 'flag',
'recordId' => (string) $id, 'title' => "Denúncia #$id"]);C#
using System.Net.Http.Headers;
using System.Net.Http.Json;
var oraculo = new HttpClient { Timeout = TimeSpan.FromSeconds(3) };
async Task AvisarOraculo(object evento)
{
try
{
using var pedido = new HttpRequestMessage(HttpMethod.Post, Environment.GetEnvironmentVariable("ORACULO_URL"))
{ Content = JsonContent.Create(evento) };
pedido.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ORACULO_CHAVE"));
using var resposta = await oraculo.SendAsync(pedido);
}
catch (Exception) { /* registar o eventId, sem dados pessoais */ }
}
await AvisarOraculo(new { contract = "oraculo.event.v1", eventId = "denuncia-142-criada", kind = "pending",
state = "open", counter = "denuncias", label = "Denúncias por responder", icon = "flag",
recordId = "142", title = "Denúncia #142", version = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() });Python
import os, time, requests
def avisar_oraculo(evento: dict) -> None:
try:
requests.post(
os.environ["ORACULO_URL"],
headers={"Authorization": f"Bearer {os.environ['ORACULO_CHAVE']}"},
json={"contract": "oraculo.event.v1", "version": int(time.time() * 1000), **evento},
timeout=3,
)
except requests.RequestException:
print("Oráculo não recebeu o evento", evento.get("eventId"))
avisar_oraculo({"eventId": "denuncia-142-criada", "kind": "pending", "state": "open",
"counter": "denuncias", "label": "Denúncias por responder", "icon": "flag",
"recordId": "142", "title": "Denúncia #142"})Lista de verificação
- Tenho o URL e a credencial da integração, guardados fora do código.
- Cada acontecimento tem um
eventIdestável (o mesmo acontecimento, o mesmoeventId). - Abrir e fechar o mesmo registo usam o mesmo
countere o mesmorecordId. - Cada contador é só de pendências ou só de incidentes.
- Envio
version(ou pelo menosoccurredAt). - Envio depois de gravar na base de dados.
- Limite de 3 s,
try/catch, e a falha não estraga o pedido do utilizador. - Nenhum campo leva conteúdo sensível.
- Testei com
X-Oraculo-Dry-Run: 1e depois com um envio real, e vi o contador em Contadores.
Problemas comuns
| Sintoma | Causa provável |
|---|---|
401 | Credencial errada, copiada com espaço ou de outra integração; ou revogada. Gera uma nova na aplicação. |
422 com «counter…» | O counter tem maiúsculas, espaços ou acentos. Usa denuncias, não Denúncias. |
422 com «recordId…» | Falta o recordId num pending ou incident. |
422 counter_kind_mismatch | O mesmo counter foi usado como pendência e como incidente. |
| O contador não desce | O fecho usa outro counter ou outro recordId do que a abertura. |
ignored_stale | Chegou um aviso mais antigo do que o último já aplicado a esse registo; é normal. Se for inesperado, confirma o version. |
400 invalid_encoding ou acentos estragados | O corpo não foi enviado em UTF-8 (típico de curl.exe no Windows com o texto no argumento). Envia o JSON a partir de um ficheiro UTF-8. |
Nada no painel, mas 202 | O projecto não está atribuído à estação do ecrã (Configurações > Estações). |
200 duplicate | Já tinha este eventId. É o comportamento certo. |