Hooks (entrada)

Muitos sistemas só sabem mandar um webhook para uma URL. Um hook transforma esse webhook num evento do notific.me, sem código do seu lado. Cada hook tem um slug e um mapeamento YAML com regras que leem o corpo, os cabeçalhos e a query string que chegaram.

A URL do hook

POST https://api.notific.me/v0/hooks/<slug>?token=<token de serviço com events:write>

• O token pode ir no cabeçalho Authorization: Bearer ou, para sistemas que só deixam configurar a URL, em ?token=. O servidor tira o token da URL antes de registrar logs.
• O evento fica com o serviço dono do token.
• ?dry_run=1 devolve o evento que seria criado, sem gravar.

A tela Hooks do app.notific.me monta a URL para você, combinando o slug com um token do serviço escolhido.

Um mapeamento

source: github                # default: the hook slug
hmac:                         # optional: validates the sender's signature
  header: X-Hub-Signature-256
  algorithm: sha256           # sha1 | sha256 | sha512
  encoding: hex               # hex | base64
  prefix: "sha256="
  secret: "shared-secret"
rules:                        # in order; the first one that matches wins
  - name: workflow-failed
    match:                    # every condition must hold (AND)
      "$header.X-GitHub-Event": workflow_run
      workflow_run.conclusion: failure
    event:
      type: ci.failed
      severity: high
      summary: "CI failed: {{ repository.name }} ({{ workflow_run.head_branch }})"
      title: CI failed
      text: "{{ workflow_run.name }} failed on {{ workflow_run.head_branch }}. {{ workflow_run.html_url }}"
      dedup_key: "ci/{{ repository.name }}/{{ workflow_run.head_branch }}"
  - name: workflow-ok
    match:
      "$header.X-GitHub-Event": workflow_run
      workflow_run.conclusion: success
    event:
      type: ci.ok
      severity: info
      summary: "CI passed: {{ repository.name }}"

Quando nenhuma regra casa, o hook responde 200 {"status":"ignored"}.

Caminhos

Campos do corpo separados por ponto (data.app.name, items.0.id). Caminhos especiais: $header.<Nome>, $query.<nome>, $slug e $now.

Operadores de match

Um valor simples significa igual, uma lista significa um destes. A forma de mapa aceita equals, in, not, regex, prefix, suffix, contains e exists:

match:
  type: { regex: "(?i)^deploy[._-]?(success|done)$" }
  status: [done, success]
  "$header.X-Event": { exists: true }

Templates

{{ caminho }} com filtros opcionais encadeados por |: default "x", lower, upper, trim, truncate 80 e json. Valor ausente vira texto vazio.

O event de uma regra aceita type, severity (padrão info), summary, title e text (montam um card simples), id (idempotência, por exemplo "{{ $header.X-GitHub-Delivery }}"), dedup_key, card_id, ttl, expires_when, retention, to e payload, todos com templates.

Presets embutidos

Alguns sistemas já têm mapeamento pronto. Hoje: dokploy (deploy concluído, deploy com falha e uma notificação genérica). Para ajustar um preset, grave seu próprio mapeamento com o mesmo slug: ele tem precedência, e apagá-lo traz o preset de volta.

Configure um hook

1. No app.notific.me, abra Hooks e crie um hook (ou comece por um preset).
2. Escreva o mapeamento. Use o teste com um corpo, cabeçalhos e query de exemplo para ver o evento que seria gerado e se ele é válido.
3. Escolha o serviço e copie a URL do hook.
4. Cole a URL no outro sistema (Dokploy, GitHub, Stripe…). Se ele assina os webhooks, adicione o bloco hmac com o segredo compartilhado.

Nota

O segredo HMAC nunca é mostrado de novo depois de salvo: o app e a API devolvem mascarado (********). Salvar o mapeamento com o valor mascarado mantém o segredo guardado.