Eventos

Um evento diz que algo aconteceu: um deploy terminou, um container caiu, chegou um lead. Todo SDK, plugin e hook fala o mesmo formato, definido pelo JSON Schema aberto event.schema.json (versão 0 do protocolo).

{
  "source": "dokploy",
  "type": "container.die",
  "severity": "high",
  "occurred_at": "2026-11-05T12:00:00Z",
  "to": ["jimmy"],
  "payload": { "host": "vps-01", "exit_code": 137 },
  "dedup_key": "vps-01/api-v2",
  "expires_when": "container.healthy",
  "content": {
    "summary": "api-v2 died on vps-01",
    "card": { "title": "Container died", "blocks": [{ "type": "metric", "label": "Crashes in 24h", "value": 3 }] }
  }
}

Campos

Campo	Obrigatório	Descrição
`source`	Sim	Quem gerou (`dokploy`, `crm`, `agente-financeiro`), de 1 a 120 caracteres. O SDK preenche a partir de `new NotificMe({ source })`.
`type`	Sim	Tipo em minúsculas separado por pontos: `container.die`, `lead.new`. Padrão `^[a-z0-9_-]+(\.[a-z0-9_-]+)*$`.
`severity`	Sim	`info`, `low`, `medium`, `high` ou `critical`. O SDK usa `info` por padrão.
`occurred_at`	Sim	Quando aconteceu (RFC 3339). O SDK usa o momento atual por padrão.
`id`	Não	Seu id para o evento, usado na idempotência. O SDK sempre envia um.
`to`	Não	Destinatários: handle, e-mail de membro ou grupo. Sem `to`, as regras e inscrições do workspace decidem.
`payload`	Não	Dados livres. O SDK envia como está (as chaves não são convertidas).
`dedup_key`	Não	Eventos com a mesma chave dentro da janela de deduplicação (1 hora por padrão, ou o `ttl` do evento) são juntados.
`ttl`	Não	Por quanto tempo a notificação faz sentido: `30m`, `2h`, `3d`.
`expires_when`	Não	Tipo de evento que encerra esta notificação, como `container.healthy`.
`card_id`	Não	Atualiza um card existente em vez de criar outro (um card vivo).
`retention`	Não	`ephemeral`, `standard` (padrão) ou `regulated`.
`content.summary`	Com `content`	Texto curto para push, relógio e canais simples (até 240 caracteres).
`content.card`	Não	O card declarativo.
`content.rich`	Não	Referência de um HTML em sandbox, sempre com `card` como alternativa.

Destinatários e consentimento

O to só resolve membros do workspace do serviço: o handle atual, um handle antigo ainda reservado ou o e-mail do vínculo. Ninguém é notificado sem consentimento: quem não aceitou o convite não é resolvido, e POST /v0/events responde 422. Remover um membro corta o acesso na hora. Veja Workspaces e membros.

Idempotência e deduplicação

Idempotência: o mesmo id enviado duas vezes é gravado uma vez. A nova tentativa recebe a resposta guardada com o cabeçalho Idempotent-Replayed: true. Reusar um id com conteúdo diferente gera 409 idempotency_conflict.
Deduplicação: uma repetição com o mesmo dedup_key dentro da janela é aceita com status: "duplicate" e duplicate_of.

Cards vivos

Eventos com o mesmo card_id atualizam o mesmo card em vez de criar notificações novas. Um deploy vai de buildando para testando e para no ar num card só. No SDK, passe live: true e depois chame update():

const deploy = await notific.send({
  type: "deploy.progress",
  summary: "Deploying api",
  live: true,
  card: { blocks: [{ type: "progress", value: 0.1, steps: ["Build", "Tests", "Rollout"], current: 0 }] },
});

await notific.update(deploy.cardId!, {
  card: { blocks: [{ type: "progress", value: 0.8, steps: ["Build", "Tests", "Rollout"], current: 2 }] },
});

Limites

Limite	Padrão
Eventos por token	600 por minuto (rajada de 100); acima disso, `429 rate_limited` com `Retry-After`
Tamanho do corpo	1 MiB
Janela de deduplicação	1 hora (o `ttl` do evento tem precedência)
Memória da idempotência	24 horas