Hooks (entrada)

Muchos sistemas solo saben enviar un webhook a una URL. Un hook convierte ese webhook en un evento de notific.me, sin código de tu lado. Cada hook tiene un slug y un mapeo YAML con reglas que leen el cuerpo, las cabeceras y la query string recibidos.

La URL del hook

POST https://api.notific.me/v0/hooks/<slug>?token=<token de servicio con events:write>

El token puede ir en la cabecera Authorization: Bearer o, para sistemas que solo permiten configurar una URL, en ?token=. El servidor lo quita de la URL antes de registrar logs.
El evento pertenece al servicio dueño del token.
?dry_run=1 devuelve el evento que se crearía, sin guardarlo.

La pantalla Hooks de app.notific.me arma la URL por ti, combinando el slug con un token del servicio elegido.

Un mapeo

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 }}"

Cuando ninguna regla coincide, el hook responde 200 {"status":"ignored"}.

Rutas

Campos del cuerpo separados por puntos (data.app.name, items.0.id). Rutas especiales: $header.<Nombre>, $query.<nombre>, $slug y $now.

Operadores de match

Un valor simple significa igual, una lista significa uno de estos. La forma de mapa acepta equals, in, not, regex, prefix, suffix, contains y exists:

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

Plantillas

{{ ruta }} con filtros opcionales encadenados por |: default "x", lower, upper, trim, truncate 80 y json. Un valor ausente se convierte en texto vacío.

El event de una regla acepta type, severity (por defecto info), summary, title y text (arman una tarjeta simple), id (idempotencia, por ejemplo "{{ $header.X-GitHub-Delivery }}"), dedup_key, card_id, ttl, expires_when, retention, to y payload, todos con plantillas.

Presets integrados

Algunos sistemas ya tienen un mapeo listo. Hoy: dokploy (despliegue correcto, despliegue fallido y una notificación genérica). Para ajustar un preset, guarda tu propio mapeo con el mismo slug: tiene prioridad, y al borrarlo vuelve el preset.

Configura un hook

En app.notific.me, abre Hooks y crea un hook (o parte de un preset).
Escribe el mapeo. Usa la prueba con un cuerpo, cabeceras y query de ejemplo para ver el evento que se generaría y si es válido.
Elige el servicio y copia la URL del hook.
Pega la URL en el otro sistema (Dokploy, GitHub, Stripe…). Si firma sus webhooks, agrega el bloque hmac con el secreto compartido.