Webhooks

O Myria pode avisar sua organização quando novos mapas TOK forem baixados e quando uma rodada terminar com sucesso ou com uma falha que interrompe o estudo.

Última atualização desta página: 2026-07-30.

Configurar

No Portal, acesse Perfil → Webhooks:

1. informe uma URL HTTPS pública;
2. marque Mapas TOK baixados, Rodadas concluídas ou com falha terminal, ou as duas opções;
3. salve o webhook;
4. guarde o segredo de assinatura mostrado na página.

A configuração vale para toda a organização. A opção TOK fica desabilitada enquanto a chave Tempook não estiver validada. Se a chave for removida ou deixar de ser válida, os eventos TOK são desligados automaticamente.

A URL não pode apontar para localhost, rede privada ou endereço sem HTTPS. O destino é validado ao salvar e novamente em cada entrega. Redirects não são seguidos.

Receber uma entrega

O Myria faz um POST com JSON. Retorne qualquer status 2xx somente depois de persistir o evento. Timeouts, redirects e respostas fora de 2xx contam como falha e podem gerar nova tentativa.

Headers:

Content-Type: application/json
User-Agent: Myria-Webhooks/1.0
X-Myria-Delivery: 4dfb20e7-94d9-4232-a510-0f0efef401b5
X-Myria-Event: rodada.finished
X-Myria-Timestamp: 1785463200
X-Myria-Signature: sha256=<assinatura hexadecimal>

O campo id do corpo e o header X-Myria-Delivery não mudam entre tentativas. Use esse valor como chave idempotente: se ele já foi processado, retorne 2xx sem repetir o efeito.

Validar a assinatura

A assinatura usa HMAC-SHA256 sobre:

X-Myria-Timestamp + "." + corpo bruto da requisição

Exemplo em Python:

import hashlib
import hmac
import time


def validar_webhook(raw_body: bytes, headers: dict, segredo: str) -> bool:
    timestamp = headers["X-Myria-Timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False

    mensagem = timestamp.encode("ascii") + b"." + raw_body
    esperado = "sha256=" + hmac.new(
        segredo.encode("utf-8"),
        mensagem,
        hashlib.sha256,
    ).hexdigest()
    recebido = headers.get("X-Myria-Signature", "")
    return hmac.compare_digest(esperado, recebido)

Valide a assinatura usando os bytes recebidos, antes de desserializar ou reformatar o JSON. Rejeitar timestamps com mais de cinco minutos reduz o risco de replay.

Use Gerar novo segredo no Perfil se o segredo for comprometido. Entregas ainda pendentes são canceladas quando a URL ou o segredo muda. Alterar a URL também gera um segredo novo, para que o destino anterior não possa assinar eventos destinados ao endpoint novo.

Formato comum

Todos os eventos têm esta estrutura:

{
  "id": "4dfb20e7-94d9-4232-a510-0f0efef401b5",
  "type": "rodada.finished",
  "created_at": "2026-07-30T21:00:00Z",
  "organization": {
    "id": 42,
    "slug": "cliente",
    "name": "Cliente"
  },
  "data": {}
}

tok.downloaded

Criado depois que um pacote TOK novo foi baixado e confirmado no repositório terceiros.

{
  "id": "9507c9e7-291b-4e56-98c7-f307906554c6",
  "type": "tok.downloaded",
  "created_at": "2026-07-30T20:55:00Z",
  "organization": {
    "id": 42,
    "slug": "cliente",
    "name": "Cliente"
  },
  "data": {
    "model": "TOKMDlp-MIN",
    "map_kind": "prevs",
    "source_path": "Comercializadora/Arquivos/PREVS/TOKMDlp-MIN/2026-07/PREVS_TOKMDlp-MIN_20260730.tar.gz",
    "repository": "terceiros",
    "repository_path": "tok/prevs/TOKMDlp-MIN/2026-07/30",
    "archive_name": "PREVS_TOKMDlp-MIN_20260730.tar.gz",
    "files_downloaded": 4
  }
}

map_kind pode ser prevs ou vazpast.

rodada.finished

Criado quando a tentativa atual de uma rodada chega a completed ou failed.

{
  "id": "4dfb20e7-94d9-4232-a510-0f0efef401b5",
  "type": "rodada.finished",
  "created_at": "2026-07-30T21:00:00Z",
  "organization": {
    "id": 42,
    "slug": "cliente",
    "name": "Cliente"
  },
  "data": {
    "outcome": "failed",
    "stops_study": true,
    "study": {
      "id": 810,
      "title": "PMO agosto"
    },
    "round": {
      "id": 991,
      "name": "newave_202608",
      "type": "newave",
      "revision": "final",
      "status": "failed",
      "run_id": "9266df859ba44db29b6967b43842cb24",
      "execution_attempts": 4,
      "finished_at": "2026-07-30T21:00:00Z"
    }
  }
}

Valores:

Campo	Significado
outcome: "completed"	A rodada terminou e seus resultados foram confirmados.
outcome: "failed"	A tentativa falhou de forma terminal e bloqueia o encadeamento dependente.
stops_study	true apenas para failed.
execution_attempts	Quantidade de lançamentos do executável dentro da tentativa; uma falha NEWAVE após quatro tentativas informa 4.

Estados nonconverged não são enviados porque o DECOMP pode continuar o encadeamento por relato. Paradas solicitadas (stopped) também não geram este evento.

Tentativas e ordem

A entrega é pelo menos uma vez. O Myria tenta até oito vezes por padrão, com espera crescente entre as tentativas. Portanto:

• deduplique sempre por id;
• não dependa da chegada estritamente ordenada entre eventos diferentes;
• responda rápido e processe de forma assíncrona se o seu trabalho for demorado;
• aceite apenas eventos com assinatura e timestamp válidos.